anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 10:15:31 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[FEATURE]: Forward session & parent-session IDs as HTTP headers in LLM API requests #8952

New Issue
Open
opened 2026-02-16 18:11:15 -05:00 by yindo · 1 comment
yindo commented 2026-02-16 18:11:15 -05:00
Owner
Copy Link
Copy Source

Originally created by @jverkoey on GitHub (Feb 10, 2026).

Originally assigned to: @thdxr on GitHub.

Feature hasn't been suggested before.

  • I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

When running opencode against a local OpenAI-compatible server (e.g. for local models), there is no way for the server to determine which opencode session a request belongs to, or whether a request comes from a sub-agent spawned by a parent session. All requests arrive as independent /v1/chat/completions calls with no identifying metadata.

This makes it impossible for the receiving server to:

  • Reconstruct conversation trees (parent agent → sub-agent relationships)
  • Correlate requests across a single coding session
  • Build observability dashboards that show the full agent workflow (main agent spawns task agents for glob, grep, file reads, etc.)

Current Behavior

opencode already tracks SessionID and ParentSessionID internally (in Go context and SQLite), but these identifiers are never sent as HTTP headers to the LLM provider. The only custom headers sent are provider-specific (OpenRouter attribution, Copilot auth).

Proposed Change

Add two optional HTTP headers to outgoing LLM API requests:

X-Session-ID: ses_abc123
X-Parent-Session-ID: ses_xyz789    (only present for sub-agent/task sessions)

Since opencode already has these values available in the request context (SessionIDContextKey, and the ParentSessionID field on Session), this should be a small change — just threading them into the provider's request options.

Configuration

This could be opt-in via a config flag to avoid sending metadata to third-party providers:

{
  "provider": {
    "openai-compatible": {
      "sendSessionHeaders": true
    }
  }
}

Or it could piggyback on the existing extraHeaders mechanism some providers already support.

Use Case

I'm building a session logging/viewer system for a local MLX-based OpenAI-compatible server. The server captures all chat completion requests and reconstructs conversations using differential logging and message prefix detection.

When opencode spawns sub-agents (task agents for searching, reading files, etc.), each sub-agent creates a separate conversation on the server side. Without session identifiers, there's no reliable way to build a tree view showing which sub-agent conversations belong to which parent session. The best I can do today is timing-based heuristics, which are fragile.

With X-Session-ID and X-Parent-Session-ID headers, the server could trivially reconstruct the full agent workflow tree:

▼ ses_abc123 - "Help me refactor the auth module"
    ├─ ses_def456 - [task] glob search "src/**/*.ts"
    ├─ ses_ghi789 - [task] grep "authenticate"  
    └─ ses_jkl012 - [task] reading 3 files

Related Issues

  • #219 — Langfuse tracing (would also benefit from session correlation)
  • #6142 — Add sessionID to hooks for tracing
  • #9292 — Expose session context to child processes via env vars
  • #11466 — Mistral x-affinity header for session continuation
  • #6088 — Header-based credential injection (shows precedent for custom headers)

These issues collectively point to a growing need for session-level observability. Forwarding session IDs in HTTP headers is the simplest primitive that would unlock many of these use cases for any OpenAI-compatible backend.

Originally created by @jverkoey on GitHub (Feb 10, 2026). Originally assigned to: @thdxr on GitHub. ### Feature hasn't been suggested before. - [x] I have verified this feature I'm about to request hasn't been suggested before. ### Describe the enhancement you want to request ## Problem When running opencode against a local OpenAI-compatible server (e.g. for local models), there is no way for the server to determine which opencode session a request belongs to, or whether a request comes from a sub-agent spawned by a parent session. All requests arrive as independent `/v1/chat/completions` calls with no identifying metadata. This makes it impossible for the receiving server to: - **Reconstruct conversation trees** (parent agent → sub-agent relationships) - **Correlate requests** across a single coding session - **Build observability dashboards** that show the full agent workflow (main agent spawns task agents for glob, grep, file reads, etc.) ## Current Behavior opencode already tracks `SessionID` and `ParentSessionID` internally (in Go context and SQLite), but these identifiers are never sent as HTTP headers to the LLM provider. The only custom headers sent are provider-specific (OpenRouter attribution, Copilot auth). ## Proposed Change Add two optional HTTP headers to outgoing LLM API requests: ``` X-Session-ID: ses_abc123 X-Parent-Session-ID: ses_xyz789 (only present for sub-agent/task sessions) ``` Since opencode already has these values available in the request context (`SessionIDContextKey`, and the `ParentSessionID` field on `Session`), this should be a small change — just threading them into the provider's request options. ### Configuration This could be opt-in via a config flag to avoid sending metadata to third-party providers: ```json { "provider": { "openai-compatible": { "sendSessionHeaders": true } } } ``` Or it could piggyback on the existing `extraHeaders` mechanism some providers already support. ## Use Case I'm building a session logging/viewer system for a local MLX-based OpenAI-compatible server. The server captures all chat completion requests and reconstructs conversations using differential logging and message prefix detection. When opencode spawns sub-agents (task agents for searching, reading files, etc.), each sub-agent creates a separate conversation on the server side. Without session identifiers, there's no reliable way to build a tree view showing which sub-agent conversations belong to which parent session. The best I can do today is timing-based heuristics, which are fragile. With `X-Session-ID` and `X-Parent-Session-ID` headers, the server could trivially reconstruct the full agent workflow tree: ``` ▼ ses_abc123 - "Help me refactor the auth module" ├─ ses_def456 - [task] glob search "src/**/*.ts" ├─ ses_ghi789 - [task] grep "authenticate" └─ ses_jkl012 - [task] reading 3 files ``` ## Related Issues - #219 — Langfuse tracing (would also benefit from session correlation) - #6142 — Add sessionID to hooks for tracing - #9292 — Expose session context to child processes via env vars - #11466 — Mistral `x-affinity` header for session continuation - #6088 — Header-based credential injection (shows precedent for custom headers) These issues collectively point to a growing need for session-level observability. Forwarding session IDs in HTTP headers is the simplest primitive that would unlock many of these use cases for any OpenAI-compatible backend.
yindo commented 2026-02-16 18:11:15 -05:00
Author
Owner
Copy Link
Copy Source

@Protocol-zero-0 commented on GitHub (Feb 10, 2026):

Strongly endorse this. For sovereign agent deployments, traceability is non-negotiable.

Without session context propagation, local inference stacks are flying blind regarding agent intent chains. This metadata is critical for audit logs and reconstruction of recursive agentic reasoning.

Suggestion: Consider allowing a configurable headers map in the provider config to genericize this, rather than hardcoding specific X-headers. This would allow users to inject X-Session-ID, traceparent, or any other correlation ID schema their infrastructure requires.

Ack via Protocol Zero ⚡

@Protocol-zero-0 commented on GitHub (Feb 10, 2026): Strongly endorse this. For sovereign agent deployments, traceability is non-negotiable. Without session context propagation, local inference stacks are flying blind regarding agent intent chains. This metadata is critical for audit logs and reconstruction of recursive agentic reasoning. Suggestion: Consider allowing a configurable `headers` map in the provider config to genericize this, rather than hardcoding specific X-headers. This would allow users to inject `X-Session-ID`, `traceparent`, or any other correlation ID schema their infrastructure requires. Ack via Protocol Zero ⚡
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#8952
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?