Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(opencode-go): 直连路径补 x-opencode-session,修复辅助模型/视觉/连接测试 400 (#5172)

Yunjin Zhangb0008c272f1b
diff --git a/apps/desktop/src/main/maker-host/__tests__/opencode-go-session.test.ts b/apps/desktop/src/main/maker-host/__tests__/opencode-go-session.test.ts
new file mode 100644
index 0000000000..2040da46a3
--- /dev/null
+++ b/apps/desktop/src/main/maker-host/__tests__/opencode-go-session.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest';
+
+import { isOpenCodeGoUpstream, withOpenCodeGoSessionHeader } from '../opencode-go-session.js';
+
+describe('isOpenCodeGoUpstream', () => {
+ it('matches the OpenCode Go preset entry points with or without /v1 and trailing slash', () => {
+ expect(isOpenCodeGoUpstream('https://opencode.ai/zen/go')).toBe(true);
+ expect(isOpenCodeGoUpstream('https://opencode.ai/zen/go/v1')).toBe(true);
+ expect(isOpenCodeGoUpstream('https://opencode.ai/zen/go/v1/')).toBe(true);
+ expect(isOpenCodeGoUpstream('https://opencode.ai/zen/go/')).toBe(true);
+ });
+
+ it('rejects other hosts, products and decorated URLs', () => {
+ expect(isOpenCodeGoUpstream('https://opencode.ai/zen')).toBe(false);
+ expect(isOpenCodeGoUpstream('https://opencode.ai/zen/v1')).toBe(false);
+ expect(isOpenCodeGoUpstream('https://opencode.ai/zen/go-extra')).toBe(false);
+ expect(isOpenCodeGoUpstream('https://example.com/zen/go/v1')).toBe(false);
+ expect(isOpenCodeGoUpstream('http://opencode.ai/zen/go/v1')).toBe(false);
+ expect(isOpenCodeGoUpstream('https://user:[email protected]/zen/go/v1')).toBe(false);
+ expect(isOpenCodeGoUpstream('https://opencode.ai/zen/go/v1?tenant=1')).toBe(false);
+ expect(isOpenCodeGoUpstream('not-a-url')).toBe(false);
+ });
+});
+
+describe('withOpenCodeGoSessionHeader', () => {
+ it('adds a per-request session id for the OpenCode Go provider id and upstream', () => {
+ for (const route of [
+ { providerId: 'opencode-go', upstream: 'https://mirror.example/zen/go/v1' },
+ { providerId: 'custom-id', upstream: 'https://opencode.ai/zen/go/v1' },
+ ]) {
+ const headers = withOpenCodeGoSessionHeader({ 'x-custom': '1' }, route);
+ expect(headers?.['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ expect(headers?.['x-custom']).toBe('1');
+ }
+ });
+
+ it('does not invent a header for unrelated routes', () => {
+ expect(
+ withOpenCodeGoSessionHeader(undefined, {
+ providerId: 'chat-only',
+ upstream: 'https://chat.example/v1',
+ }),
+ ).toBeUndefined();
+ expect(
+ withOpenCodeGoSessionHeader(
+ { 'x-custom': '1' },
+ {
+ providerId: 'chat-only',
+ upstream: 'https://chat.example/v1',
+ },
+ ),
+ ).toEqual({ 'x-custom': '1' });
+ });
+
+ it('preserves an explicitly configured non-empty session header case-insensitively', () => {
+ const headers = withOpenCodeGoSessionHeader(
+ { 'X-OpenCode-Session': 'user-fixed-id' },
+ { providerId: 'opencode-go', upstream: 'https://opencode.ai/zen/go/v1' },
+ );
+ expect(headers).toEqual({ 'X-OpenCode-Session': 'user-fixed-id' });
+ });
+
+ it('keeps only one session header when the user value coexists with empty or duplicate variants', () => {
+ for (const configured of ['', ' ']) {
+ const headers = withOpenCodeGoSessionHeader(
+ {
+ 'x-opencode-session': configured,
+ 'X-OpenCode-Session': 'user-fixed-id',
+ 'x-custom': '1',
+ },
+ { providerId: 'opencode-go', upstream: 'https://opencode.ai/zen/go/v1' },
+ );
+ // 两个非空同名键同样只能留一个(保留首见拼写),否则 fetch 合并出 `', <value>'`。
+ expect(
+ Object.keys(headers!).filter((key) => key.toLowerCase() === 'x-opencode-session'),
+ ).toEqual(['X-OpenCode-Session']);
+ expect(headers!['X-OpenCode-Session']).toBe('user-fixed-id');
+ expect(headers!['x-custom']).toBe('1');
+ }
+ const duplicated = withOpenCodeGoSessionHeader(
+ { 'x-opencode-session': 'second', 'X-OpenCode-Session': 'first' },
+ { providerId: 'opencode-go', upstream: 'https://opencode.ai/zen/go/v1' },
+ );
+ expect(duplicated).toEqual({ 'x-opencode-session': 'second' });
+ });
+
+ it('recognizes a preset-created connection after its id and endpoint changed', () => {
+ const headers = withOpenCodeGoSessionHeader(
+ { 'x-custom': '1' },
+ {
+ providerId: 'opencode-go-mirror',
+ catalogPresetId: 'opencode-go',
+ upstream: 'https://mirror.example/zen-go/v1',
+ },
+ );
+ expect(headers?.['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ expect(headers?.['x-custom']).toBe('1');
+ // 其它预设身份 + 非 Go 地址不应被误判。
+ expect(
+ withOpenCodeGoSessionHeader(undefined, {
+ providerId: 'claude-proxy',
+ catalogPresetId: 'moonshot',
+ upstream: 'https://api.moonshot.example/v1',
+ }),
+ ).toBeUndefined();
+ });
+
+ it('treats an empty configured session header as absent, including case variants', () => {
+ for (const configured of ['', ' ']) {
+ for (const name of ['x-opencode-session', 'X-OpenCode-Session']) {
+ const headers = withOpenCodeGoSessionHeader(
+ { [name]: configured, 'x-custom': '1' },
+ { providerId: 'opencode-go', upstream: 'https://opencode.ai/zen/go/v1' },
+ );
+ // 同名不同拼写只能留一个,否则 fetch 会合并成 `', <uuid>'` 非法复合值。
+ expect(
+ Object.keys(headers!).filter((key) => key.toLowerCase() === 'x-opencode-session'),
+ ).toEqual(['x-opencode-session']);
+ expect(headers!['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ expect(headers!['x-custom']).toBe('1');
+ }
+ }
+ });
+
+ it('generates a fresh id per request when no session id is given', () => {
+ const route = { providerId: 'opencode-go', upstream: 'https://opencode.ai/zen/go/v1' };
+ const first = withOpenCodeGoSessionHeader(undefined, route);
+ const second = withOpenCodeGoSessionHeader(undefined, route);
+ expect(first?.['x-opencode-session']).not.toBe(second?.['x-opencode-session']);
+ });
+
+ it('derives a deterministic id for spawn-env consumers so rebuilds stay byte-identical', () => {
+ const route = {
+ providerId: 'opencode-go',
+ upstream: 'https://opencode.ai/zen/go/v1',
+ sessionId: 'session-1',
+ };
+ const first = withOpenCodeGoSessionHeader(undefined, route);
+ const second = withOpenCodeGoSessionHeader(undefined, route);
+ expect(first?.['x-opencode-session']).toBe(second?.['x-opencode-session']);
+ expect(first?.['x-opencode-session']).toMatch(/^[0-9a-f]{32}$/);
+
+ const otherSession = withOpenCodeGoSessionHeader(undefined, {
+ ...route,
+ sessionId: 'session-2',
+ });
+ expect(otherSession?.['x-opencode-session']).not.toBe(first?.['x-opencode-session']);
+
+ const trailingSlash = withOpenCodeGoSessionHeader(undefined, {
+ ...route,
+ upstream: 'https://opencode.ai/zen/go/v1/',
+ });
+ expect(trailingSlash?.['x-opencode-session']).toBe(first?.['x-opencode-session']);
+ });
+});
diff --git a/apps/desktop/src/main/maker-host/__tests__/providerDiagnostics.test.ts b/apps/desktop/src/main/maker-host/__tests__/providerDiagnostics.test.ts
index 018b71d3c9..f5d13851fc 100644
--- a/apps/desktop/src/main/maker-host/__tests__/providerDiagnostics.test.ts
+++ b/apps/desktop/src/main/maker-host/__tests__/providerDiagnostics.test.ts
@@ -134,6 +134,45 @@ describe('buildProbeRequest', () => {
});
});
+ it('adds the OpenCode Go session header to the probe request', () => {
+ const { url, init } = buildProbeRequest({
+ agent: 'codex',
+ wireProtocol: 'openai-chat',
+ baseUrl: 'https://opencode.ai/zen/go/v1',
+ modelId: 'deepseek-v4.1-flash',
+ apiKey: 'go-secret',
+ });
+ expect(url).toBe('https://opencode.ai/zen/go/v1/chat/completions');
+ const headers = init.headers as Record<string, string>;
+ expect(headers['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ expect(headers.authorization).toBe('Bearer go-secret');
+ });
+
+ it('recognizes an OpenCode Go preset on a mirror base URL', () => {
+ const { init } = buildProbeRequest({
+ agent: 'codex',
+ wireProtocol: 'openai-chat',
+ baseUrl: 'https://mirror.example/v1',
+ catalogPresetId: 'opencode-go',
+ modelId: 'deepseek-v4.1-flash',
+ apiKey: 'go-secret',
+ });
+ const headers = init.headers as Record<string, string>;
+ expect(headers['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ });
+
+ it('leaves other presets on mirror base URLs without the session header', () => {
+ const { init } = buildProbeRequest({
+ agent: 'codex',
+ wireProtocol: 'openai-chat',
+ baseUrl: 'https://mirror.example/v1',
+ catalogPresetId: 'moonshot',
+ modelId: 'kimi-k2',
+ apiKey: 'sk-mirror',
+ });
+ expect((init.headers as Record<string, string>)['x-opencode-session']).toBeUndefined();
+ });
+
it('Codex Anthropic Messages probe matches runtime joining for a versioned base URL', () => {
const { url } = buildProbeRequest({
agent: 'codex',
diff --git a/apps/desktop/src/main/maker-host/__tests__/providerRoute.test.ts b/apps/desktop/src/main/maker-host/__tests__/providerRoute.test.ts
index 5bab8d816a..6fa8663db7 100644
--- a/apps/desktop/src/main/maker-host/__tests__/providerRoute.test.ts
+++ b/apps/desktop/src/main/maker-host/__tests__/providerRoute.test.ts
@@ -1715,6 +1715,33 @@ describe('resolveVisionBackendRoute(视觉桥复用统一路由器)', () =>
expect(resolveVisionBackendRoute('openrouter', 'qwen/qwen-vl-max', null)).toBeNull();
});
+ it('目录预设身份随路由返回:改地址后视觉直连仍能识别 OpenCode Go', () => {
+ setCustomProviders([
+ buildUserProvider({
+ id: 'opencode-go-mirror',
+ name: 'OpenCode Go (mirror)',
+ runtimes: {
+ codex: {
+ baseUrl: 'https://mirror.example/v1',
+ wireProtocol: 'openai-chat',
+ catalogPresetId: 'opencode-go',
+ models: [{ id: 'deepseek-v4.1-flash', name: 'DeepSeek V4.1 Flash' }],
+ },
+ },
+ }),
+ ]);
+ setCustomProviderKeyReader((id) => (id === 'opencode-go-mirror' ? 'sk-go' : null));
+ try {
+ const routed = resolveVisionBackendRoute('opencode-go-mirror', 'deepseek-v4.1-flash', null);
+ expect(routed).not.toBeNull();
+ expect(routed?.catalogPresetId).toBe('opencode-go');
+ expect(routed?.upstream).toBe('https://mirror.example/v1');
+ } finally {
+ setCustomProviders([]);
+ setCustomProviderKeyReader(() => null);
+ }
+ });
+
it('gateway-key 无动态端点 → null(网关不可用)', () => {
setVisionGatewayKeyReader(() => KEY);
expect(resolveVisionBackendRoute('xd', 'codex/gpt-5.6-luna', null)).toBeNull();
diff --git a/apps/desktop/src/main/maker-host/index.ts b/apps/desktop/src/main/maker-host/index.ts
index 6daa0275e8..59bc65be68 100644
--- a/apps/desktop/src/main/maker-host/index.ts
+++ b/apps/desktop/src/main/maker-host/index.ts
@@ -2308,7 +2308,7 @@ export function getMaker(): Maker {
},
getGhostRosterPrompt,
// 仅为命中视觉桥目标的 Pi 模型注册 Layer C 工具。
- resolvePiVisionBridgeEnv: (model) =>
+ resolvePiVisionBridgeEnv: (model, sessionId) =>
buildPiVisionBridgeEnv(
{
getProviderById: (providerId) =>
@@ -2320,6 +2320,7 @@ export function getMaker(): Maker {
fetch: outboundFetch,
},
model,
+ sessionId,
),
// 远端 Pi:给 session 标 remoteHostId 的, PiAgent 通过这个钩子拿远端
// transport — SSH 连接复用 ConnectionPool (remote-ssh feature 起的),
diff --git a/apps/desktop/src/main/maker-host/opencode-go-session.ts b/apps/desktop/src/main/maker-host/opencode-go-session.ts
new file mode 100644
index 0000000000..a06927c80f
--- /dev/null
+++ b/apps/desktop/src/main/maker-host/opencode-go-session.ts
@@ -0,0 +1,116 @@
+/**
+ * opencode-go-session —— OpenCode Go 直连请求的会话头适配。
+ *
+ * OpenCode Go 自 2026-09-06 起强制要求每个请求携带稳定会话标识,缺失直接 400
+ * `MissingSessionID`(上游文档 https://opencode.ai/docs/go/#where-can-i-use-it)。
+ *
+ * 会话路径不需要本模块:各客户端/桥自带的上游可识别头——Claude Code 的
+ * `x-claude-code-session-id`、Codex 的 `session-id`、Pi 当前构建自己注入的
+ * `x-opencode-session`,以及 Codex chat bridge 的 thread-id → x-opencode-session
+ * 映射(#4073 / #4075)。本模块只服务**从零构造请求头、没有上述任何原生会话头的
+ * 直连路径**:辅助模型 one-shot、供应商「测试连接」探测、视觉桥。
+ *
+ * 路由识别有三路信号:运行时供应商 id、目录预设身份(`catalogPresetId`,从预设创建后
+ * 即使把地址改成自建转发、或复制连接得到新 id 也仍保留)、上游地址。三者任一命中即视为
+ * OpenCode Go:多补一个会话头对非 Go 端点无害(未知头被忽略),漏了则整条直连链路 400。
+ *
+ * 取值分两种:
+ * - 普通直连(host 每请求发起):随机 UUID,一次 one-shot 即一次独立对话;
+ * - spawn env 注入(层 C:Pi 视觉桥 env):必须**确定性派生**(pi-harness §4.10
+ * spawn env 稳定性)——同 sessionId + 同后端恒等,断链重连不变;用随机值会让
+ * 远端 daemon 的 envHash 变化 → kill + 全新建。
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+
+import { CONVERSATION_SESSION_HEADER } from '@cindy/responses-chat-bridge';
+
+export interface OpenCodeGoSessionRoute {
+ /** 运行时供应商 id(从预设创建时通常是预设 id,复制/改名后可不同)。 */
+ providerId: string;
+ /** 目录预设身份(`CatalogModel.catalogPresetId`);存量连接可能没有。 */
+ catalogPresetId?: string;
+ upstream: string;
+ /**
+ * spawn env 注入场景传入逻辑 session id:头值按 sessionId + 后端身份确定性派生。
+ * 缺省 = 每请求随机 UUID(host 直连路径)。
+ */
+ sessionId?: string;
+}
+
+/** OpenCode Go 预设入口:`https://opencode.ai/zen/go` 或带 `/v1`。 */
+export function isOpenCodeGoUpstream(baseUrl: string): boolean {
+ let url: URL;
+ try {
+ url = new URL(baseUrl);
+ } catch {
+ return false;
+ }
+ if (url.protocol !== 'https:' || url.hostname !== 'opencode.ai') return false;
+ if (url.username || url.password || url.search || url.hash) return false;
+ const path = url.pathname.replace(/\/+$/, '');
+ return path === '/zen/go' || path === '/zen/go/v1';
+}
+
+/**
+ * 按会话头名(大小写不敏感)拆分:其余头 + 首个**非空**用户值的拼写。
+ *
+ * 同名不同拼写一起交给 fetch 会被合并成 `', <value>'` 这类非法复合值
+ * (responses-chat-bridge 同因修复);历史配置还常留空占位值。这里一次遍历同时完成
+ * 「剔除空占位」「同名只留一个」「保留用户显式值」,调用方无需再二次去重。
+ */
+function splitSessionHeader(headers: Record<string, string> | undefined): {
+ rest: Record<string, string>;
+ userKey: string | null;
+ userValue: string | null;
+} {
+ const normalized = CONVERSATION_SESSION_HEADER.toLowerCase();
+ const rest: Record<string, string> = {};
+ let userKey: string | null = null;
+ let userValue: string | null = null;
+ for (const [key, value] of Object.entries(headers ?? {})) {
+ if (key.toLowerCase() !== normalized) {
+ rest[key] = value;
+ continue;
+ }
+ if (userKey === null && typeof value === 'string' && value.trim()) {
+ userKey = key;
+ userValue = value;
+ }
+ }
+ return { rest, userKey, userValue };
+}
+
+function stableSessionHeaderValue(route: OpenCodeGoSessionRoute, sessionId: string): string {
+ return createHash('sha256')
+ .update(`${sessionId}\n${route.providerId}\n${route.upstream.trim().replace(/\/+$/, '')}`)
+ .digest('hex')
+ .slice(0, 32);
+}
+
+/**
+ * 给 OpenCode Go 路由的直连请求补 `x-opencode-session`;其余路由原样返回
+ * (undefined 表示本来就没有额外头)。供应商 id、目录预设身份或上游地址任一命中
+ * 即视为 OpenCode Go:用户把预设改到自建转发、复制连接得到新 id 都需要该头,
+ * 反向(自定义 id 指向官方入口)也要覆盖。
+ *
+ * 调用方已显式配置**非空**同名头(历史手工 workaround)时保留用户值,且结果里
+ * 同名键只留一个——空占位 + 大小写变体的组合交给 fetch 会被合并成非法复合值。
+ */
+export function withOpenCodeGoSessionHeader(
+ headers: Record<string, string> | undefined,
+ route: OpenCodeGoSessionRoute,
+): Record<string, string> | undefined {
+ const isOpenCodeGo =
+ route.providerId === 'opencode-go' ||
+ route.catalogPresetId === 'opencode-go' ||
+ isOpenCodeGoUpstream(route.upstream);
+ if (!isOpenCodeGo) return headers;
+ const { rest, userKey, userValue } = splitSessionHeader(headers);
+ if (userKey !== null && userValue !== null) {
+ return { ...rest, [userKey]: userValue };
+ }
+ const sessionId = route.sessionId?.trim();
+ const value = sessionId ? stableSessionHeaderValue(route, sessionId) : randomUUID();
+ return { ...rest, [CONVERSATION_SESSION_HEADER]: value };
+}
diff --git a/apps/desktop/src/main/maker-host/provider-diagnostics.ts b/apps/desktop/src/main/maker-host/provider-diagnostics.ts
index 481380022c..542403d146 100644
--- a/apps/desktop/src/main/maker-host/provider-diagnostics.ts
+++ b/apps/desktop/src/main/maker-host/provider-diagnostics.ts
@@ -34,6 +34,7 @@ import {
type ProviderErrorCode,
} from '../../shared/providerErrors.js';
import { getActiveCatalog } from './active-catalog.js';
+import { withOpenCodeGoSessionHeader } from './opencode-go-session.js';
import { createMakerLogger } from './logger-adapter.js';
import { outboundFetch } from './outbound-fetch.js';
import { hostCredentialEndpointAllowed, invocationModelRecord, probePiProvider, requiresNativeProviderAuth } from './pi-provider-transport.js';
@@ -133,9 +134,12 @@ function normalizedHeaders(headers: Record<string, string> | undefined): Record<
export function buildProbeRequest(spec: ProviderProbeSpec): { url: string; init: RequestInit } {
const mustStripCredentialHeaders =
!!spec.apiKey || spec.authMethod === 'none' || spec.authMethod === 'oauth';
- const headers = mustStripCredentialHeaders
- ? withoutCredentialHeaders(spec.headers)
- : normalizedHeaders(spec.headers);
+ const headers = withOpenCodeGoSessionHeader(
+ mustStripCredentialHeaders
+ ? withoutCredentialHeaders(spec.headers)
+ : normalizedHeaders(spec.headers),
+ { providerId: spec.catalogPresetId ?? '', catalogPresetId: spec.catalogPresetId, upstream: spec.baseUrl },
+ ) ?? {};
headers['content-type'] = 'application/json';
if (spec.wireProtocol === 'google-generative-ai') {
if (spec.apiKey) headers['x-goog-api-key'] = spec.apiKey;
diff --git a/apps/desktop/src/main/maker-host/provider-route.ts b/apps/desktop/src/main/maker-host/provider-route.ts
index aa13dd952f..24d60cfada 100644
--- a/apps/desktop/src/main/maker-host/provider-route.ts
+++ b/apps/desktop/src/main/maker-host/provider-route.ts
@@ -1240,6 +1240,17 @@ function pickVisionAgent(provider: Provider, modelId: string): AgentKind | null
return null;
}
+/**
+ * provider 在某 runtime 由哪个目录预设创建(预设身份随模型投影带出,用户改地址后仍保留)。
+ * 视觉/探测这类直连路径用它识别「从 OpenCode Go 预设创建、但运行时 id 或地址已改」的连接。
+ */
+export function providerRuntimeCatalogPresetId(
+ provider: Provider,
+ agent: AgentKind,
+): string | undefined {
+ return (provider.models[agent] ?? []).find((model) => model.catalogPresetId)?.catalogPresetId;
+}
+
export function resolveVisionBackendRoute(
providerId: string,
modelId: string,
@@ -1253,6 +1264,8 @@ export function resolveVisionBackendRoute(
/** 路由指定的额外请求头(headerOverride 去掉客户端凭证头后)。视觉桥直连需要它们
* (如 anthropic-version / x-api-key / 自定义 provider 头),否则后端会拒请求(P1)。 */
headers: Record<string, string>;
+ /** 该 runtime 的目录预设身份(如 'opencode-go'):直连路径据此补会话头。 */
+ catalogPresetId?: string;
} | null {
if (isProviderRouteMutationInProgress(providerId)) return null;
const provider = getActiveCatalog().providers.find((p) => p.id === providerId);
@@ -1263,6 +1276,7 @@ export function resolveVisionBackendRoute(
if (!agent) return null;
const routing = providerRoutingForModel(provider, agent, modelId);
if (!routing || routing.disabled) return null;
+ const catalogPresetId = providerRuntimeCatalogPresetId(provider, agent);
// 转发上游前还原 model id(对齐 rewriteModelIdForProvider)。
// XD 投影给 Codex 的模型走 Claude Messages 面时,`codex/` 是路由前缀不是后端真实模型名,
@@ -1373,7 +1387,7 @@ export function resolveVisionBackendRoute(
const key = gatewayKeyReader();
if (key) headers['x-api-key'] = key;
}
- return { upstream, requestPath, wireProtocol, model, authorization, headers };
+ return { upstream, requestPath, wireProtocol, model, authorization, headers, ...(catalogPresetId ? { catalogPresetId } : {}) };
}
/** 当前生效的 XD 网关 key(host 注入;默认空)。 */
diff --git a/apps/desktop/src/main/utility-model/__tests__/oneShotCandidates.test.ts b/apps/desktop/src/main/utility-model/__tests__/oneShotCandidates.test.ts
index 659ee0baef..5c997f0234 100644
--- a/apps/desktop/src/main/utility-model/__tests__/oneShotCandidates.test.ts
+++ b/apps/desktop/src/main/utility-model/__tests__/oneShotCandidates.test.ts
@@ -804,6 +804,139 @@ describe('utility one-shot candidates', () => {
reasoning_effort: 'low',
messages: [{ role: 'user', content: 'generate' }],
});
+ expect(vi.mocked(fetchMock).mock.calls[0]?.[1]?.headers).not.toHaveProperty('x-opencode-session');
+ });
+
+ it('attaches the OpenCode Go session header to an auxiliary chat request', async () => {
+ activeCatalog.mockReturnValue({
+ providers: [{
+ id: 'opencode-go',
+ name: 'OpenCode Go',
+ source: 'user',
+ agents: ['codex'],
+ auth: { method: 'apiKey' },
+ routing: {
+ codex: {
+ upstream: 'https://opencode.ai/zen/go/v1',
+ wireProtocol: 'openai-chat',
+ authStrategy: 'api-key-header',
+ },
+ },
+ models: {
+ codex: [{ id: 'deepseek-v4.1-flash', name: 'DeepSeek V4.1 Flash', contextWindow: 1_000_000 }],
+ },
+ }],
+ } as never);
+ readCustomKey.mockReturnValue('go-secret');
+ fetchMock.mockResolvedValueOnce({
+ ok: true,
+ text: async () => JSON.stringify({
+ choices: [{ message: { content: 'task name' } }],
+ }),
+ } as never);
+
+ const result = await requestExplicitUtilityText('name this task', {
+ providerId: 'opencode-go',
+ agentKind: 'codex',
+ model: 'deepseek-v4.1-flash',
+ maxTokens: 32,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'task name' });
+ expect(fetchMock).toHaveBeenCalledWith(
+ 'https://opencode.ai/zen/go/v1/chat/completions',
+ expect.anything(),
+ );
+ const headers = vi.mocked(fetchMock).mock.calls[0]?.[1]?.headers as Record<string, string>;
+ expect(headers['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ expect(headers.Authorization).toBe('Bearer go-secret');
+ });
+
+ it('recognizes a preset-created provider after its id and endpoint changed', async () => {
+ activeCatalog.mockReturnValue({
+ providers: [{
+ id: 'opencode-go-mirror',
+ name: 'OpenCode Go (mirror)',
+ source: 'user',
+ agents: ['codex'],
+ auth: { method: 'apiKey' },
+ routing: {
+ codex: {
+ upstream: 'https://mirror.example/v1',
+ wireProtocol: 'openai-chat',
+ authStrategy: 'api-key-header',
+ },
+ },
+ models: {
+ codex: [{
+ id: 'deepseek-v4.1-flash',
+ name: 'DeepSeek V4.1 Flash',
+ contextWindow: 1_000_000,
+ catalogPresetId: 'opencode-go',
+ }],
+ },
+ }],
+ } as never);
+ readCustomKey.mockReturnValue('go-secret');
+ fetchMock.mockResolvedValueOnce({
+ ok: true,
+ text: async () => JSON.stringify({ choices: [{ message: { content: 'task name' } }] }),
+ } as never);
+
+ const result = await requestExplicitUtilityText('name this task', {
+ providerId: 'opencode-go-mirror',
+ agentKind: 'codex',
+ model: 'deepseek-v4.1-flash',
+ maxTokens: 32,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'task name' });
+ const headers = vi.mocked(fetchMock).mock.calls[0]?.[1]?.headers as Record<string, string>;
+ expect(headers['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ });
+
+ it('keeps the OpenCode Go session header on the minimal-body retry after a 400', async () => {
+ activeCatalog.mockReturnValue({
+ providers: [{
+ id: 'opencode-go',
+ name: 'OpenCode Go',
+ source: 'user',
+ agents: ['codex'],
+ auth: { method: 'apiKey' },
+ routing: {
+ codex: {
+ upstream: 'https://opencode.ai/zen/go/v1',
+ wireProtocol: 'openai-chat',
+ authStrategy: 'api-key-header',
+ },
+ },
+ models: {
+ codex: [{ id: 'deepseek-v4.1-flash', name: 'DeepSeek V4.1 Flash', contextWindow: 1_000_000 }],
+ },
+ }],
+ } as never);
+ readCustomKey.mockReturnValue('go-secret');
+ fetchMock
+ .mockResolvedValueOnce({ ok: false, status: 400, body: { cancel: async () => undefined } } as never)
+ .mockResolvedValueOnce({
+ ok: true,
+ text: async () => JSON.stringify({ choices: [{ message: { content: 'task name' } }] }),
+ } as never);
+
+ const result = await requestExplicitUtilityText('name this task', {
+ providerId: 'opencode-go',
+ agentKind: 'codex',
+ model: 'deepseek-v4.1-flash',
+ maxTokens: 32,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'task name' });
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ const firstHeaders = vi.mocked(fetchMock).mock.calls[0]?.[1]?.headers as Record<string, string>;
+ const retryHeaders = vi.mocked(fetchMock).mock.calls[1]?.[1]?.headers as Record<string, string>;
+ expect(firstHeaders['x-opencode-session']).toBeTruthy();
+ expect(retryHeaders['x-opencode-session']).toBe(firstHeaders['x-opencode-session']);
+ expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).not.toHaveProperty('thinking');
});
it('maps disabled thinking to Ollama reasoning_effort none', async () => {
diff --git a/apps/desktop/src/main/utility-model/oneShotCandidates.ts b/apps/desktop/src/main/utility-model/oneShotCandidates.ts
index 78d420883c..6af87f5c18 100644
--- a/apps/desktop/src/main/utility-model/oneShotCandidates.ts
+++ b/apps/desktop/src/main/utility-model/oneShotCandidates.ts
@@ -25,6 +25,7 @@ import {
import { readModelDisableOverrides } from '../maker-host/model-disable-store.js';
import { isModelDisabled, isProviderDisabled } from '@cindy/model-providers';
import { isProviderRouteMutationInProgress } from '../maker-host/provider-route.js';
+import { withOpenCodeGoSessionHeader } from '../maker-host/opencode-go-session.js';
import { effectiveXdGatewayBaseUrl } from '../model-access/effectiveEndpoint.js';
import { readCustomProviderKey } from '../secrets/providerSecretStore.js';
import { MANAGED_OLLAMA_PROVIDER_ID } from '../../shared/localModelRuntime.js';
@@ -760,6 +761,9 @@ async function requestExplicitProviderText(
// which would silently turn a Claude request into a Codex request.
const model = requestedModel || configuredModels.find((item) =>
isModelSelectableForNewRoute(item, { userProvider: provider?.source === 'user' }))?.id || '';
+ // 预设身份随模型投影带出:从 OpenCode Go 预设创建后再改地址/复制连接时,运行时 id 与
+ // URL 都可能对不上,补会话头仍要认得出来(见 opencode-go-session.ts 的三路识别)。
+ const catalogPresetId = configuredModels.find((item) => item.id === model)?.catalogPresetId;
const selectedRouting = agentKind ? provider?.routing[agentKind] : undefined;
const transport: UtilityModelTransport =
agentKind === 'codex' && selectedRouting?.wireProtocol !== 'openai-chat'
@@ -955,7 +959,11 @@ async function requestExplicitProviderText(
requestPath: routing.requestPath,
wireProtocol,
isOllama,
- headers: routing.headerOverride,
+ headers: withOpenCodeGoSessionHeader(routing.headerOverride, {
+ providerId: provider.id,
+ catalogPresetId,
+ upstream: routing.upstream,
+ }),
credential: credential ?? '',
authStrategy,
model,
diff --git a/apps/desktop/src/main/vision-bridge/__tests__/pi-vision-bridge-env.test.ts b/apps/desktop/src/main/vision-bridge/__tests__/pi-vision-bridge-env.test.ts
index ef1fbf10ad..07227e2f77 100644
--- a/apps/desktop/src/main/vision-bridge/__tests__/pi-vision-bridge-env.test.ts
+++ b/apps/desktop/src/main/vision-bridge/__tests__/pi-vision-bridge-env.test.ts
@@ -28,7 +28,12 @@ function mockController(shouldBridge: (model: string) => boolean = () => true):
mockedController.mockReturnValue({ shouldBridge, describeImage: vi.fn() } as never);
}
-function depsWithProvider(provider: { id: string; routingAuth: string }): VisionChannelDeps {
+function depsWithProvider(provider: {
+ id: string;
+ routingAuth: string;
+ upstream?: string;
+ catalogPresetId?: string;
+}): VisionChannelDeps {
return {
getProviderById: (providerId: string) =>
providerId === provider.id
@@ -41,11 +46,21 @@ function depsWithProvider(provider: { id: string; routingAuth: string }): Vision
routing: {
'claude-code': {
wireProtocol: 'openai-chat',
- upstream: 'https://api.example.com/v1',
+ upstream: provider.upstream ?? 'https://api.example.com/v1',
authStrategy: provider.routingAuth,
},
},
- models: { 'claude-code': [{ id: 'vision-x', name: 'Vision X' }] },
+ models: {
+ 'claude-code': [
+ {
+ id: 'vision-x',
+ name: 'Vision X',
+ ...(provider.catalogPresetId
+ ? { catalogPresetId: provider.catalogPresetId }
+ : {}),
+ },
+ ],
+ },
} as never)
: null,
readCustomProviderKey: () => 'sk-test',
@@ -72,12 +87,12 @@ beforeEach(() => {
describe('buildPiVisionBridgeEnv', () => {
it('returns null when disabled', () => {
mockedSettings.mockReturnValue(settings({ enabled: false }));
- expect(buildPiVisionBridgeEnv(depsWithProvider({ id: 'user-x', routingAuth: 'api-key-header' }), 'deepseek-v4')).toBeNull();
+ expect(buildPiVisionBridgeEnv(depsWithProvider({ id: 'user-x', routingAuth: 'api-key-header' }), 'deepseek-v4', 'session-1')).toBeNull();
});
it('returns null when no primary backend', () => {
mockedSettings.mockReturnValue(settings({ primary: null }));
- expect(buildPiVisionBridgeEnv(depsWithProvider({ id: 'user-x', routingAuth: 'api-key-header' }), 'deepseek-v4')).toBeNull();
+ expect(buildPiVisionBridgeEnv(depsWithProvider({ id: 'user-x', routingAuth: 'api-key-header' }), 'deepseek-v4', 'session-1')).toBeNull();
});
it('returns null when current model is not a vision-bridge target (shouldBridge false)', () => {
@@ -86,16 +101,16 @@ describe('buildPiVisionBridgeEnv', () => {
// 不注入 env、pi 不注册 vision 工具(零干扰——不因别的模型配置而改变本模型工具面)。
mockController((model) => model !== 'claude-sonnet');
const d = depsWithProvider({ id: 'user-x', routingAuth: 'api-key-header' });
- expect(buildPiVisionBridgeEnv(d, 'claude-sonnet')).toBeNull();
+ expect(buildPiVisionBridgeEnv(d, 'claude-sonnet', 'session-1')).toBeNull();
// 命中模型 → 正常注入。
- expect(buildPiVisionBridgeEnv(d, 'deepseek-v4')).not.toBeNull();
+ expect(buildPiVisionBridgeEnv(d, 'deepseek-v4', 'session-1')).not.toBeNull();
});
it('returns null when primary backend cannot be resolved (unsupported auth)', () => {
mockedSettings.mockReturnValue(settings());
// provider 用 OAuth 策略 → resolveVisionBackendEndpoint 抛错 → primary null → 整体 null。
const d = depsWithProvider({ id: 'user-x', routingAuth: 'provider-oauth-header' });
- expect(buildPiVisionBridgeEnv(d, 'deepseek-v4')).toBeNull();
+ expect(buildPiVisionBridgeEnv(d, 'deepseek-v4', 'session-1')).toBeNull();
});
it('serializes primary + fallback backend spec into env', () => {
@@ -107,7 +122,7 @@ describe('buildPiVisionBridgeEnv', () => {
);
const d = depsWithProvider({ id: 'user-x', routingAuth: 'api-key-header' });
// fallback provider user-y 不在 deps 里 → resolve null,主后端仍可用。
- const env = buildPiVisionBridgeEnv(d, 'deepseek-v4');
+ const env = buildPiVisionBridgeEnv(d, 'deepseek-v4', 'session-1');
expect(env).not.toBeNull();
expect(env![PI_VISION_BRIDGE_ENV]).toBeTruthy();
const parsed = JSON.parse(env![PI_VISION_BRIDGE_ENV]);
@@ -132,10 +147,35 @@ describe('buildPiVisionBridgeEnv', () => {
}),
);
const d = depsWithProvider({ id: 'user-x', routingAuth: 'api-key-header' });
- const env = buildPiVisionBridgeEnv(d, 'deepseek-v4');
+ const env = buildPiVisionBridgeEnv(d, 'deepseek-v4', 'session-1');
expect(env).not.toBeNull();
const parsed = JSON.parse(env![PI_VISION_BRIDGE_ENV]);
expect(parsed.fallback).not.toBeNull();
expect(parsed.fallback.model).toBe('vision-y');
});
+
+ it('derives a stable OpenCode Go session header so the spawn env survives reconnects', () => {
+ mockedSettings.mockReturnValue(settings({ primary: { providerId: 'opencode-go', modelId: 'vision-x' } }));
+ const d = depsWithProvider({ id: 'opencode-go', routingAuth: 'api-key-header' });
+ const first = JSON.parse(buildPiVisionBridgeEnv(d, 'deepseek-v4', 'session-1')![PI_VISION_BRIDGE_ENV]);
+ const second = JSON.parse(buildPiVisionBridgeEnv(d, 'deepseek-v4', 'session-1')![PI_VISION_BRIDGE_ENV]);
+ const other = JSON.parse(buildPiVisionBridgeEnv(d, 'deepseek-v4', 'session-2')![PI_VISION_BRIDGE_ENV]);
+ expect(first.primary.headers['x-opencode-session']).toMatch(/^[0-9a-f]{32}$/);
+ expect(second.primary.headers['x-opencode-session']).toBe(first.primary.headers['x-opencode-session']);
+ expect(other.primary.headers['x-opencode-session']).not.toBe(first.primary.headers['x-opencode-session']);
+ });
+
+ it('recognizes a preset-created provider after its id and endpoint changed', () => {
+ mockedSettings.mockReturnValue(settings({ primary: { providerId: 'go-mirror', modelId: 'vision-x' } }));
+ const d = depsWithProvider({
+ id: 'go-mirror',
+ routingAuth: 'api-key-header',
+ upstream: 'https://mirror.example/v1',
+ catalogPresetId: 'opencode-go',
+ });
+ const parsed = JSON.parse(
+ buildPiVisionBridgeEnv(d, 'deepseek-v4', 'session-1')![PI_VISION_BRIDGE_ENV],
+ );
+ expect(parsed.primary.headers['x-opencode-session']).toMatch(/^[0-9a-f]{32}$/);
+ });
});
diff --git a/apps/desktop/src/main/vision-bridge/__tests__/vision-channel.test.ts b/apps/desktop/src/main/vision-bridge/__tests__/vision-channel.test.ts
index eb382f3e5e..9f6bd5d4e1 100644
--- a/apps/desktop/src/main/vision-bridge/__tests__/vision-channel.test.ts
+++ b/apps/desktop/src/main/vision-bridge/__tests__/vision-channel.test.ts
@@ -277,6 +277,60 @@ describe('describeImageWithProvider', () => {
expect(body.messages[0].content[1].image_url.url).toBe('https://x/y.png');
});
+ it('adds the OpenCode Go session header to the vision request', async () => {
+ const fetchMock = vi.fn().mockResolvedValue({
+ ok: true,
+ json: async () => ({ choices: [{ message: { content: 'ok' } }] }),
+ } as unknown as Response);
+ const d = deps({ fetch: fetchMock as unknown as typeof globalThis.fetch });
+ d.getProviderById = () =>
+ fakeProvider({
+ id: 'opencode-go',
+ routing: {
+ 'claude-code': {
+ wireProtocol: 'openai-chat',
+ upstream: 'https://opencode.ai/zen/go/v1',
+ authStrategy: 'api-key-header',
+ },
+ },
+ });
+ await describeImageWithProvider('opencode-go', 'vision-x', { imageUrl: 'https://x/y.png' }, d);
+ const init = fetchMock.mock.calls[0]?.[1] as { headers: Record<string, string> };
+ expect(init.headers['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ });
+
+ it('recognizes a preset-created vision provider after its id and endpoint changed', async () => {
+ const fetchMock = vi.fn().mockResolvedValue({
+ ok: true,
+ json: async () => ({ choices: [{ message: { content: 'ok' } }] }),
+ } as unknown as Response);
+ const d = deps({ fetch: fetchMock as unknown as typeof globalThis.fetch });
+ d.getProviderById = () =>
+ fakeProvider({
+ id: 'opencode-go-mirror',
+ routing: {
+ 'claude-code': {
+ wireProtocol: 'openai-chat',
+ upstream: 'https://mirror.example/v1',
+ authStrategy: 'api-key-header',
+ },
+ },
+ models: {
+ 'claude-code': [{
+ id: 'vision-x',
+ name: 'Vision X',
+ contextWindow: 200000,
+ efforts: ['low'],
+ defaultEffort: null,
+ catalogPresetId: 'opencode-go',
+ }],
+ },
+ });
+ await describeImageWithProvider('opencode-go-mirror', 'vision-x', { imageUrl: 'https://x/y.png' }, d);
+ const init = fetchMock.mock.calls[0]?.[1] as { headers: Record<string, string> };
+ expect(init.headers['x-opencode-session']).toMatch(/^[0-9a-f-]{36}$/);
+ });
+
it('propagates HTTP error as VisionBackendError', async () => {
const fetchMock = vi.fn().mockResolvedValue({
ok: false,
diff --git a/apps/desktop/src/main/vision-bridge/pi-vision-bridge-env.ts b/apps/desktop/src/main/vision-bridge/pi-vision-bridge-env.ts
index 34db898cde..5edd8089d3 100644
--- a/apps/desktop/src/main/vision-bridge/pi-vision-bridge-env.ts
+++ b/apps/desktop/src/main/vision-bridge/pi-vision-bridge-env.ts
@@ -5,11 +5,15 @@
* 只能经 env 传递。本模块在 host 侧解析视觉桥配置(主/fallback 后端 → 三协议端点 +
* model + key + wireProtocol),序列化成单个 JSON env(`CINDY_PI_VISION_BRIDGE`),
* PiAgent 把它注入 spawnEnv 并纳入 piSecretEnvNames 剥离面(防获批 bash 读到 API key)。
+ * OpenCode Go 后端还会补一个 `x-opencode-session`:头值按 sessionId + 后端身份确定性
+ * 派生 —— spawn env 必须同 session 重建逐字节稳定(pi-harness §4.10),随机值会让
+ * 远端 daemon envHash 变化而 kill + 全新建。
*
* 对齐 docs/vision-bridge-design.md 层 C + 五、视觉通道。
*/
import { readVisionBridgeSettings } from './vision-bridge-settings-store.js';
import { getVisionBridgeController } from './vision-bridge-controller.js';
+import { withOpenCodeGoSessionHeader } from '../maker-host/opencode-go-session.js';
import {
resolveVisionBackendEndpoint,
VisionBackendError,
@@ -42,6 +46,7 @@ function resolveSpec(
providerId: string,
modelId: string,
deps: VisionChannelDeps,
+ sessionId: string | undefined,
): PiVisionBackendSpec | null {
try {
const ep = resolveVisionBackendEndpoint(providerId, modelId, deps);
@@ -50,7 +55,13 @@ function resolveSpec(
requestPath: ep.requestPath,
model: ep.model,
authorization: ep.authorization,
- headers: ep.headers,
+ headers:
+ withOpenCodeGoSessionHeader(ep.headers, {
+ providerId,
+ catalogPresetId: ep.catalogPresetId,
+ upstream: ep.upstream,
+ sessionId,
+ }) ?? {},
wireProtocol: ep.wireProtocol,
};
} catch (err) {
@@ -68,6 +79,7 @@ function resolveSpec(
export function buildPiVisionBridgeEnv(
deps: VisionChannelDeps,
model: string,
+ sessionId?: string,
): Record<string, string> | null {
const settings = readVisionBridgeSettings();
if (!settings.enabled) return null;
@@ -75,10 +87,10 @@ export function buildPiVisionBridgeEnv(
// 按 session model 判定(与层 B / 层 A 同源 shouldBridge):未命中目标模型
// 不注入 env、不注册 vision 工具(codex P1 零干扰要求)。
if (!getVisionBridgeController()?.shouldBridge(model)) return null;
- const primary = resolveSpec(settings.primary.providerId, settings.primary.modelId, deps);
+ const primary = resolveSpec(settings.primary.providerId, settings.primary.modelId, deps, sessionId);
if (!primary) return null;
const fallback = settings.fallback
- ? resolveSpec(settings.fallback.providerId, settings.fallback.modelId, deps)
+ ? resolveSpec(settings.fallback.providerId, settings.fallback.modelId, deps, sessionId)
: null;
const payload: PiVisionBridgeEnvPayload = {
enabled: true,
diff --git a/apps/desktop/src/main/vision-bridge/vision-channel.ts b/apps/desktop/src/main/vision-bridge/vision-channel.ts
index 76cb681cec..9802d2be4f 100644
--- a/apps/desktop/src/main/vision-bridge/vision-channel.ts
+++ b/apps/desktop/src/main/vision-bridge/vision-channel.ts
@@ -20,6 +20,9 @@ import fs from 'node:fs/promises';
import { resolvePiModelWireProtocol, type AgentKind, type Provider } from '@cindy/model-providers';
+import { withOpenCodeGoSessionHeader } from '../maker-host/opencode-go-session.js';
+import { providerRuntimeCatalogPresetId } from '../maker-host/provider-route.js';
+
/** 视觉后端执行失败(带原因)。调用方据此决定 fallback 或回退。 */
export class VisionBackendError extends Error {
readonly code:
@@ -299,11 +302,16 @@ export async function describeImageWithProvider(
const endpoint = resolveVisionBackendEndpoint(providerId, modelId, deps);
const url = `${endpoint.upstream}${endpoint.requestPath.startsWith('/') ? endpoint.requestPath : `/${endpoint.requestPath}`}`;
// 合并路由额外头(anthropic-version / x-api-key / 自定义 provider 头)+ Authorization。
- // endpoint.headers 已过滤客户端凭证头,与 authorization 无冲突。
- const headers: Record<string, string> = {
+ // endpoint.headers 已过滤客户端凭证头,与 authorization 无冲突。OpenCode Go 直连
+ // 需补会话头(缺失上游 400 MissingSessionID);每次识别请求即一次独立对话,随机 UUID。
+ const headers: Record<string, string> = withOpenCodeGoSessionHeader({
...endpoint.headers,
...(endpoint.authorization ? { authorization: endpoint.authorization } : {}),
- };
+ }, {
+ providerId,
+ catalogPresetId: endpoint.catalogPresetId,
+ upstream: endpoint.upstream,
+ }) ?? {};
const imageUrl = await resolveImageUrl(input);
const prompt =
input.prompt && input.prompt.trim().length > 0 ? input.prompt.trim() : DEFAULT_VISION_PROMPT;
@@ -535,6 +543,8 @@ export interface VisionBackendEndpoint {
headers: Record<string, string>;
/** wire 协议(决定请求体/响应解析形态)。 */
wireProtocol: VisionWireProtocol;
+ /** 该 runtime 的目录预设身份(如 'opencode-go'):改地址后仍保留,直连路径据此补会话头。 */
+ catalogPresetId?: string;
}
/**
@@ -567,6 +577,7 @@ export function resolveVisionBackendEndpoint(
throw new VisionBackendError('not-found', `provider ${providerId} has no usable routing`);
}
const routing = provider.routing[agent]!;
+ const catalogPresetId = providerRuntimeCatalogPresetId(provider, agent);
const wireProtocol = wireProtocolFor(provider, agent, modelId);
if (!wireProtocol) {
throw new VisionBackendError(
@@ -594,6 +605,7 @@ export function resolveVisionBackendEndpoint(
authorization: headers.authorization ?? null,
headers: visionRouteHeaders(routing),
wireProtocol,
+ ...(catalogPresetId ? { catalogPresetId } : {}),
};
}
const headers = applyAuthStrategy(provider, agent, deps);
@@ -604,5 +616,6 @@ export function resolveVisionBackendEndpoint(
authorization: headers.authorization ?? null,
headers: visionRouteHeaders(routing),
wireProtocol,
+ ...(catalogPresetId ? { catalogPresetId } : {}),
};
}
diff --git a/packages/maker-core/src/agents/base-agent.ts b/packages/maker-core/src/agents/base-agent.ts
index b647ddfb7c..abc82f4a66 100644
--- a/packages/maker-core/src/agents/base-agent.ts
+++ b/packages/maker-core/src/agents/base-agent.ts
@@ -925,9 +925,11 @@ export interface AgentDeps {
* cindy-bridge 的 vision 工具读取。缺省 = 不注入(视觉桥工具不可用,零干扰)。
* model 参数供 host 按 session 模型判定是否命中视觉桥目标模型——未命中返回 null,
* 保证非目标/已有视觉能力的 Pi 模型不注册 vision 工具、不改变工具面(零干扰)。
+ * sessionId 供需要上游会话头的后端(OpenCode Go)确定性派生头值:spawn env 必须
+ * 同 session 重建逐字节稳定(pi-harness §4.10),不得用随机值。
* 返回的键应纳入 piSecretEnvNames 剥离面(host 实现应把含 key 的键名一并声明)。
*/
- resolvePiVisionBridgeEnv?: (model: string) => Record<string, string> | null;
+ resolvePiVisionBridgeEnv?: (model: string, sessionId?: string) => Record<string, string> | null;
/**
* Host-owned arbitration for capabilities that overlap with harness-native
diff --git a/packages/maker-core/src/agents/pi/index.ts b/packages/maker-core/src/agents/pi/index.ts
index 38327613af..de95231659 100644
--- a/packages/maker-core/src/agents/pi/index.ts
+++ b/packages/maker-core/src/agents/pi/index.ts
@@ -5110,7 +5110,8 @@ export class PiAgent extends BaseAgent {
// 键名可能含 API key,须纳入 piSecretEnvNames 剥离面。
// 传当前 session model:未命中视觉桥目标模型的 Pi 模型不注入 env、不注册
// vision 工具(零干扰,不因别的模型配置了视觉桥而改变本模型工具面)。
- const visionBridgeEnv = this.deps.resolvePiVisionBridgeEnv?.(opts.model) ?? null;
+ // sessionId 供 OpenCode Go 后端确定性派生会话头(spawn env 必须稳定)。
+ const visionBridgeEnv = this.deps.resolvePiVisionBridgeEnv?.(opts.model, opts.sessionId) ?? null;
// 这些值必须留在 Pi 父进程,供 models.json 的 $ENV 请求期解析及 bridge
// client 使用;cindy-bridge 用该**仅含变量名**的清单在 bash spawn 边界剥离
// 真值,阻止 LLM shell 绕过工具审批直连 localhost proxy/MCP 或盗用 BYOM key。