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(pi): learn cache compatibility per route and bound recovery

xuzini-xzn8cb7a3118d0a
diff --git a/apps/desktop/src/main/maker-host/__tests__/pi-native-compat-overrides-store.test.ts b/apps/desktop/src/main/maker-host/__tests__/pi-native-compat-overrides-store.test.ts
new file mode 100644
index 0000000000..23e16bf386
--- /dev/null
+++ b/apps/desktop/src/main/maker-host/__tests__/pi-native-compat-overrides-store.test.ts
@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+const root = vi.hoisted(() => ({ path: '' }));
+vi.mock('electron', () => ({ app: { getPath: () => root.path } }));
+vi.mock('../logger-adapter.js', () => ({ desktopMakerLogger: { child: () => ({ info: vi.fn(), warn: vi.fn() }) } }));
+import { readPiNativeCompatOverride as read, recordPiNativeCompatOverride as record } from '../pi-native-compat-overrides-store.js';
+root.path = fs.mkdtempSync(path.join(os.tmpdir(), 'cindy-pi-compat-'));
+const file = path.join(root.path, 'pi-native-compat-overrides.json');
+const a = 'a'.repeat(64), b = 'b'.repeat(64);
+const fix = { supportsLongCacheRetention: false };
+afterAll(() => fs.rmSync(root.path, { recursive: true, force: true }));
+beforeEach(() => { fs.rmSync(file, { force: true }); });
+describe('learned cache compatibility', () => {
+ it('persists only the permitted fix and isolates connection, wire model and route', async () => {
+ expect(await record('a', 'model', { ...fix, supportsStore: true }, a)).toBe(true);
+ expect(read('a', 'model', a)).toEqual(fix);
+ expect(read('b', 'model', a)).toBeUndefined();
+ expect(read('a', 'other', a)).toBeUndefined();
+ expect(read('a', 'model', b)).toBeUndefined();
+ expect(read('a', 'model')).toBeUndefined();
+ expect(fs.readFileSync(file, 'utf8')).not.toContain('supportsStore');
+ });
+ it('merges concurrent updates without losing another model', async () => {
+ expect(await Promise.all([record('a', 'one', fix, a), record('a', 'two', fix, a)])).toEqual([true, true]);
+ expect(read('a', 'one', a)).toEqual(fix);
+ expect(read('a', 'two', a)).toEqual(fix);
+ });
+ it('does not overwrite malformed files or report an unpersisted success', async () => {
+ fs.writeFileSync(file, '{bad-json');
+ expect(await record('a', 'model', fix, a)).toBe(false);
+ expect(fs.readFileSync(file, 'utf8')).toBe('{bad-json');
+ });
+ it('does not import unscoped legacy records into a new route', () => {
+ fs.writeFileSync(file, JSON.stringify({ models: { a: { model: fix } } }));
+ expect(read('a', 'model', a)).toBeUndefined();
+ });
+ it('allows precise reset by removing an entry and observes file replacement', async () => {
+ await record('a', 'model', fix, a);
+ const replacement = file + '.replacement';
+ fs.writeFileSync(replacement, JSON.stringify({ routes: {} }));
+ fs.renameSync(replacement, file);
+ expect(read('a', 'model', a)).toBeUndefined();
+ });
+ it('rejects missing routes, controls and arbitrary compat patches', async () => {
+ expect(await record('a', 'model', fix)).toBe(false);
+ expect(await record('a', 'model\n', fix, a)).toBe(false);
+ expect(await record('a', 'model', { supportsStore: false }, a)).toBe(false);
+ expect(fs.existsSync(file)).toBe(false);
+ });
+});
diff --git a/apps/desktop/src/main/maker-host/__tests__/piNativeProviders.test.ts b/apps/desktop/src/main/maker-host/__tests__/piNativeProviders.test.ts
index 1ac5163a8b..cce1b0a8ff 100644
--- a/apps/desktop/src/main/maker-host/__tests__/piNativeProviders.test.ts
+++ b/apps/desktop/src/main/maker-host/__tests__/piNativeProviders.test.ts
@@ -2366,8 +2366,9 @@ describe('buildPiNativeProvidersFromConfigs', () => {
);
expect(providers).toHaveLength(1);
expect(providers[0]).toMatchObject({ api, baseUrl: 'http://127.0.0.1:9999',
+ cacheIdentityBaseUrl: 'https://openrouter.ai/api/v1',
headers: { 'x-cindy-pi-provider-id': 'openrouter-test', 'x-cindy-pi-session-token': '$CINDY_PI_SESSION_TOKEN' },
- models: [{ id: 'google/gemini-test', baseUrl: 'http://127.0.0.1:9999' }],
+ models: [{ id: 'google/gemini-test', baseUrl: 'http://127.0.0.1:9999', cacheIdentityBaseUrl: 'https://openrouter.ai/api/v1' }],
});
expect(env).toEqual({});
});
diff --git a/apps/desktop/src/main/maker-host/pi-host.ts b/apps/desktop/src/main/maker-host/pi-host.ts
index 09c11dcd58..b3f7900715 100644
--- a/apps/desktop/src/main/maker-host/pi-host.ts
+++ b/apps/desktop/src/main/maker-host/pi-host.ts
@@ -119,6 +119,7 @@ import {
} from './pi-gateway-model-catalog.js';
import { isExclusiveXaiModelId } from '../../shared/subscriptionModels.js';
import { resolvePiRuntimeModelDescriptor, resolveModelDefaultContextWindow, resolveModelContextProviderId } from './catalog-to-descriptors.js';
+import { readPiNativeCompatOverride } from './pi-native-compat-overrides-store.js';
import {
resolveManagedPiNativePackagePaths,
resolveManagedPiPackageResources,
@@ -1390,6 +1391,7 @@ export function buildPiNativeProvidersFromConfigs(
// The proxy already retains the supplier base path (e.g. /api/v1).
// OpenAI SDKs append /chat/completions or /responses themselves.
baseUrl: authMethod === 'oauth' ? oauthProxyEndpoint! : rt.baseUrl,
+ ...(authMethod === 'oauth' ? { cacheIdentityBaseUrl: rt.baseUrl } : {}),
api: providerApi,
apiKeyEnvVar,
...(headers && Object.keys(headers).length > 0 ? { headers } : {}),
@@ -1427,6 +1429,7 @@ export function buildPiNativeProvidersFromConfigs(
m.route && explicitRouteApi === modelApi ? explicitRoute?.baseUrl : undefined;
const spec = {
id: m.id,
+ ...(authMethod === 'oauth' ? { cacheIdentityBaseUrl: modelBaseUrl ?? rt.baseUrl } : {}),
...(resolved?.supportsFastMode !== undefined ? { supportsFastMode: resolved.supportsFastMode } : {}),
...(m.api || m.piApi || modelApi !== providerApi ? { api: modelApi } : {}),
...(authMethod === 'oauth'
@@ -1899,6 +1902,10 @@ export function buildPiAgent(opts: BuildPiAgentOpts): PiAgent | null {
return new PiAgent({
resolveSessionEnvironment: resolveCompanionRuntimeEnvironment,
getDisabledSkillPaths: readDisabledSkillPaths,
+ // 上游拒收可选请求字段(如 prompt_cache_retention / prompt_cache_key)后学到的 per-model
+ // compat 修正,写 models.json 时合并;只改 compat,不动路由与凭证。
+ resolvePiNativeCompatOverride: (providerId, modelId, routeKey) =>
+ readPiNativeCompatOverride(providerId, modelId, routeKey),
getManagedSkills: listCindyManagedSkills,
scanLocalCustomizations,
resolveModelContextLimit: (providerId, modelId) => {
diff --git a/apps/desktop/src/main/maker-host/pi-native-compat-overrides-store.ts b/apps/desktop/src/main/maker-host/pi-native-compat-overrides-store.ts
new file mode 100644
index 0000000000..fa8efb9d39
--- /dev/null
+++ b/apps/desktop/src/main/maker-host/pi-native-compat-overrides-store.ts
@@ -0,0 +1,61 @@
+/** Learned Pi cache compatibility, scoped to connection + wire model + route digest.
+ * Internal override, not a user preference. Delete an entry to re-evaluate support.
+ * Unreadable files are preserved; a failed write never authorizes replay.
+ */
+import { app } from 'electron';
+import path from 'node:path';
+import { desktopMakerLogger } from './logger-adapter.js';
+import { createOverrideSettingsFile } from './override-settings-file.js';
+
+type CacheOverride = { supportsLongCacheRetention: false };
+interface PiNativeCompatOverrides { routes: Record<string, CacheOverride> }
+const log = desktopMakerLogger.child('pi-native-compat-overrides-store');
+const DEFAULTS: PiNativeCompatOverrides = { routes: {} };
+function identity(providerId: string, modelId: string, routeKey?: string): string | undefined {
+ if (!routeKey || !/^[a-f0-9]{64}$/.test(routeKey)) return undefined;
+ if (![providerId, modelId].every((v) => typeof v === 'string' && v.length > 0 && v.length <= 512 && !/[\u0000-\u001f\u007f]/.test(v))) return undefined;
+ return JSON.stringify([providerId, modelId, routeKey]);
+}
+function normalize(raw: unknown): PiNativeCompatOverrides {
+ const routes: Record<string, CacheOverride> = Object.create(null);
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { routes };
+ const source = (raw as { routes?: unknown }).routes;
+ if (!source || typeof source !== 'object' || Array.isArray(source)) return { routes };
+ for (const [key, value] of Object.entries(source)) {
+ try {
+ const parts: unknown = JSON.parse(key);
+ if (!Array.isArray(parts) || parts.length !== 3 || !parts.every((v) => typeof v === 'string')
+ || identity(parts[0], parts[1], parts[2]) !== key) continue;
+ if (value && typeof value === 'object' && (value as CacheOverride).supportsLongCacheRetention === false) {
+ routes[key] = { supportsLongCacheRetention: false };
+ }
+ } catch { /* Invalid identities are not executable configuration. */ }
+ }
+ return { routes };
+}
+const store = createOverrideSettingsFile<PiNativeCompatOverrides>({
+ filePath: () => path.join(app.getPath('userData'), 'pi-native-compat-overrides.json'),
+ defaults: DEFAULTS, normalize, log, label: 'pi native compat overrides',
+ maxBytes: 256 * 1024, preserveUnreadableFile: true,
+ logLoadedValue: false, logReadErrorDetails: false,
+});
+export function readPiNativeCompatOverride(providerId: string, modelId: string, routeKey?: string): CacheOverride | undefined {
+ const key = identity(providerId, modelId, routeKey);
+ if (!key) return undefined;
+ store.invalidateIfChanged();
+ return store.read().routes[key] ? { supportsLongCacheRetention: false } : undefined;
+}
+export async function recordPiNativeCompatOverride(providerId: string, modelId: string,
+ compat: Record<string, unknown>, routeKey?: string): Promise<boolean> {
+ const key = identity(providerId, modelId, routeKey);
+ if (!key || compat.supportsLongCacheRetention !== false) return false;
+ try {
+ await store.updateAtomic((current) => ({ routes: {
+ ...current.value.routes, [key]: { supportsLongCacheRetention: false },
+ } }));
+ return readPiNativeCompatOverride(providerId, modelId, routeKey)?.supportsLongCacheRetention === false;
+ } catch {
+ log.warn('pi cache compatibility could not be persisted');
+ return false;
+ }
+}
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/contextOverflowRollover.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/contextOverflowRollover.test.ts
index 2b3f934d5e..aca0727fbe 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/contextOverflowRollover.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/contextOverflowRollover.test.ts
@@ -340,6 +340,8 @@ describe('createContextOverflowRollover', () => {
findLatestRebuildMeta: vi.fn(async () => null),
getLiveSession: vi.fn(
(): {
+ instanceId?: string;
+ getTurnGeneration?(): number;
isTurnRunning(): boolean;
listBackgroundTasks?(): ReadonlyArray<unknown>;
getUsageSnapshot?: () => {
@@ -358,6 +360,9 @@ describe('createContextOverflowRollover', () => {
setPendingHandoff: vi.fn(),
readPendingHandoffGeneration: vi.fn(() => 3),
replayUserMessage: vi.fn(async () => ({ accepted: true })),
+ readPiNativeCompatOverride: vi.fn((): Record<string, unknown> | undefined => undefined),
+ recordPiNativeCompatOverride: vi.fn(async () => true),
+ hasExternalRecoveryOwner: vi.fn(() => false),
onRebuilt: vi.fn(),
withCloseSuppressed: async <T>(_sessionId: string, fn: () => Promise<T>) => fn(),
log: { info: vi.fn(), warn: vi.fn() },
@@ -1096,6 +1101,395 @@ describe('createContextOverflowRollover', () => {
expect(deps.onRebuilt).not.toHaveBeenCalled();
});
+ describe('pi provider compat self-heal', () => {
+ const receipt = { piCacheRecoverySafe: true, piCacheCompatibility: { providerId: 'opencode-go', modelId: 'glm-5.3-flash', wireModelId: 'glm-5.3-flash', routeKey: 'a'.repeat(64), applied: false } };
+ const rejection =
+ '400: {"param":"prompt_cache_retention","type":"invalid_request_error","message":'
+ + '"Error from provider (Console Go): Upstream request failed: [invalid_request_error] '
+ + 'prompt_cache_retention is not supported by this endpoint; use prompt_cache_options"}';
+
+ function makePiDeps(source: OverflowSourceMessage[]) {
+ const deps = makeDeps(source);
+ deps.getSessionRow.mockResolvedValue({
+ status: 'active',
+ source: 'desktop',
+ agentKind: 'pi',
+ remoteHostId: null,
+ clearedAt: null,
+ sdkSessionId: '/tmp/glm.jsonl',
+ contextTokens: 0,
+ contextWindow: 1_000_000,
+ model: 'glm-5.3-flash',
+ providerId: 'opencode-go',
+ });
+ return deps;
+ }
+
+ it('learns the per-model compat fix once and replays the failed turn', async () => {
+ const deps = makePiDeps([
+ msg('user', '继续修这个 bug', 'u1', 1),
+ msg('assistant', '改完了,正在跑测试', 'a1', 2),
+ msg('user', '再跑一遍', 'u2', 3),
+ ]);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(
+ rollover.tryRecover('s1', { ...receipt, reason: 'unsupported-request-option', message: rejection }),
+ ).resolves.toBe(true);
+
+ expect(deps.recordPiNativeCompatOverride).toHaveBeenCalledWith(
+ 'opencode-go',
+ 'glm-5.3-flash',
+ { supportsLongCacheRetention: false },
+ 'a'.repeat(64),
+ );
+ expect(deps.closeSession).toHaveBeenCalledWith('s1');
+ // 重建用的 models.json 已去掉被拒收字段,重放同一轮用户消息即重试。
+ expect(deps.replayUserMessage).toHaveBeenCalledWith(
+ 's1',
+ '再跑一遍',
+ undefined,
+ expect.objectContaining({
+ continueFromHistory: true,
+ sourceUserContent: '再跑一遍',
+ sourceUserClientId: 'u2',
+ }),
+ );
+ expect(deps.onRebuilt).toHaveBeenCalledWith('s1');
+ // 不发布 context-overflow 式的手递手重建文案。
+ expect(deps.commitRebuild).not.toHaveBeenCalled();
+ expect(deps.setPendingHandoff).not.toHaveBeenCalled();
+ });
+
+ it('leaves non-target 400s to the normal error surface', async () => {
+ const deps = makePiDeps([msg('user', '继续', 'u1', 1)]);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(
+ rollover.tryRecover('s1', {
+ message: '400: {"type":"invalid_request_error","message":"prompt_cache_retention conflicts with prompt_cache_options"}',
+ }),
+ ).resolves.toBe(false);
+ expect(deps.recordPiNativeCompatOverride).not.toHaveBeenCalled();
+ expect(deps.closeSession).not.toHaveBeenCalled();
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ });
+
+ it.each(['late-instance', 'late-generation', 'changed-instance', 'changed-generation', 'new-input', 'cancel'])('does not retire or replay a changed source: %s', async (scenario) => {
+ const source = [msg('user', 'original', 'u1', 1)];
+ const deps = makePiDeps(source);
+ let instanceId = 'i1';
+ let generation = 1;
+ deps.getLiveSession.mockImplementation(() => ({ instanceId, getTurnGeneration: () => generation, isTurnRunning: () => false }));
+ deps.recordPiNativeCompatOverride.mockImplementation(async () => {
+ if (scenario === 'changed-instance') instanceId = 'i2';
+ if (scenario === 'changed-generation') generation = 2;
+ if (scenario === 'new-input') source.push(msg('user', 'new input', 'u2', 2));
+ if (scenario === 'cancel') rollover.cancelRecovery('s1');
+ return true;
+ });
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+ const result = rollover.tryRecover('s1', { ...receipt, message: rejection }, {
+ instanceId: scenario === 'late-instance' ? 'old' : 'i1',
+ generation: scenario === 'late-generation' ? 0 : 1,
+ });
+ // Cancellation is consumed by the existing recovery abort handler.
+ await expect(result).resolves.toBe(scenario === 'cancel');
+ expect(deps.closeSession).not.toHaveBeenCalled();
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ if (scenario.startsWith('late')) expect(deps.recordPiNativeCompatOverride).not.toHaveBeenCalled();
+ });
+
+ it.each(['missing-receipt', 'already-applied', 'wrong-provider', 'wrong-model'])('does not learn from an unverified route: %s', async (scenario) => {
+ const deps = makePiDeps([msg('user', 'original', 'u1', 1)]);
+ const route = { ...receipt.piCacheCompatibility };
+ if (scenario === 'already-applied') route.applied = true;
+ if (scenario === 'wrong-provider') route.providerId = 'another-connection';
+ if (scenario === 'wrong-model') route.modelId = 'another-model';
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+ await expect(rollover.tryRecover('s1', { message: rejection, piCacheCompatibility: scenario === 'missing-receipt' ? undefined : route, piCacheRecoverySafe: true })).resolves.toBe(false);
+ expect(deps.recordPiNativeCompatOverride).not.toHaveBeenCalled();
+ expect(deps.closeSession).not.toHaveBeenCalled();
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ });
+
+ it('learns but never replays output that has not reached persisted history', async () => {
+ const deps = makePiDeps([msg('user', 'original', 'u1', 1)]);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+ await expect(rollover.tryRecover('s1', { ...receipt, message: rejection, piCacheRecoverySafe: false })).resolves.toBe(false);
+ expect(deps.recordPiNativeCompatOverride).toHaveBeenCalledOnce();
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ });
+
+ it('applies an already-learned override to a runtime that never had it', async () => {
+ // 同一 provider/model 的另一个会话先学到并重建;本会话启动时的 models.json 还没
+ // 有该覆盖,普通发送也不会刷新模型配置 —— 这里必须让它应用覆盖并重建一次。
+ const deps = makePiDeps([
+ msg('user', '继续修这个 bug', 'u1', 1),
+ msg('assistant', '改完了,正在跑测试', 'a1', 2),
+ msg('user', '再跑一遍', 'u2', 3),
+ ]);
+ deps.readPiNativeCompatOverride.mockReturnValue({ supportsLongCacheRetention: false });
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(
+ rollover.tryRecover('s1', { ...receipt, reason: 'unsupported-request-option', message: rejection }),
+ ).resolves.toBe(true);
+
+ expect(deps.recordPiNativeCompatOverride).not.toHaveBeenCalled();
+ expect(deps.closeSession).toHaveBeenCalledWith('s1');
+ expect(deps.replayUserMessage).toHaveBeenCalledWith(
+ 's1',
+ '再跑一遍',
+ undefined,
+ expect.objectContaining({ continueFromHistory: true, sourceUserClientId: 'u2' }),
+ );
+ expect(deps.onRebuilt).toHaveBeenCalledWith('s1');
+ });
+
+ it('does not rebuild a runtime that already rebuilt with the learned fix', async () => {
+ const deps = makePiDeps([
+ msg('user', '继续修这个 bug', 'u1', 1),
+ msg('assistant', '改完了,正在跑测试', 'a1', 2),
+ msg('user', '再跑一遍', 'u2', 3),
+ ]);
+ deps.readPiNativeCompatOverride.mockReturnValue({ supportsLongCacheRetention: false });
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+ const failure = { ...receipt, reason: 'unsupported-request-option', message: rejection };
+
+ // 第一次:旧 runtime 应用磁盘上的覆盖并重建、重放。
+ await expect(
+ rollover.tryRecover('s1', failure, { instanceId: 'i1', generation: 1 }),
+ ).resolves.toBe(true);
+ expect(deps.closeSession).toHaveBeenCalledTimes(1);
+ expect(deps.replayUserMessage).toHaveBeenCalledTimes(1);
+
+ // 重建后的新一轮仍然收到同一类 400:覆盖没解决问题,直接交常规错误面,
+ // 绝不再次 close/重放(否则同一条 400 会无限重建)。
+ await expect(
+ rollover.tryRecover('s1', failure, { instanceId: 'i2', generation: 2 }),
+ ).resolves.toBe(false);
+ expect(deps.closeSession).toHaveBeenCalledTimes(1);
+ expect(deps.replayUserMessage).toHaveBeenCalledTimes(1);
+ expect(deps.onRebuilt).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not let one model rebuild block self-heal after a model switch', async () => {
+ const row = {
+ status: 'active',
+ source: 'desktop',
+ agentKind: 'pi',
+ remoteHostId: null,
+ clearedAt: null,
+ sdkSessionId: '/tmp/glm.jsonl',
+ contextTokens: 0,
+ contextWindow: 1_000_000,
+ model: 'glm-5.3-flash',
+ providerId: 'opencode-go',
+ };
+ const deps = makePiDeps([
+ msg('user', '继续修这个 bug', 'u1', 1),
+ msg('assistant', '改完了,正在跑测试', 'a1', 2),
+ msg('user', '再跑一遍', 'u2', 3),
+ ]);
+ deps.getSessionRow.mockResolvedValue(row);
+ // 两个 pair 的覆盖都已被学到(另一个会话先学到的),唯一差别是本会话的重建历史。
+ deps.readPiNativeCompatOverride.mockReturnValue({ supportsLongCacheRetention: false });
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+ const failure = { ...receipt, reason: 'unsupported-request-option', message: rejection };
+
+ await expect(
+ rollover.tryRecover('s1', failure, { instanceId: 'i1', generation: 1 }),
+ ).resolves.toBe(true);
+ expect(deps.closeSession).toHaveBeenCalledTimes(1);
+
+ // 用户切到同 provider 的另一个模型:它的覆盖是别的会话后来学到的,本会话的
+ // runtime 还没应用过 —— 不能被 glm 那次重建的记录挡住。
+ row.model = 'other-model';
+ failure.piCacheCompatibility = { ...receipt.piCacheCompatibility, modelId: 'other-model', wireModelId: 'other-model' };
+ deps.listMessages.mockResolvedValue([msg('user', 'new input', 'u3', 4)]);
+ await expect(
+ rollover.tryRecover('s1', failure, { instanceId: 'i2', generation: 2 }),
+ ).resolves.toBe(true);
+ expect(deps.closeSession).toHaveBeenCalledTimes(2);
+ expect(deps.replayUserMessage).toHaveBeenCalledTimes(2);
+ });
+
+ it('learns the fix but does not replay when the plan cannot replay', async () => {
+ // 零产出守卫(无用户消息/已有副作用)不阻止学习:关掉旧 runtime 并把修正落盘,
+ // 下一次发送重建时就生效。
+ const deps = makePiDeps([
+ msg('assistant', '已经改了文件', 'a1', 1),
+ msg('error', { ...receipt, reason: 'unsupported-request-option', message: rejection }, 'e1', 2),
+ ]);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(
+ rollover.tryRecover('s1', { ...receipt, reason: 'unsupported-request-option', message: rejection }),
+ ).resolves.toBe(false);
+ expect(deps.recordPiNativeCompatOverride).toHaveBeenCalledWith(
+ 'opencode-go',
+ 'glm-5.3-flash',
+ { supportsLongCacheRetention: false },
+ 'a'.repeat(64),
+ );
+ expect(deps.closeSession).toHaveBeenCalledWith('s1');
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ });
+
+ it('learns the fix but leaves replay to an external dispatcher turn', async () => {
+ // Orca/scheduler 派单轮次:正文经 wire 投影可能退化,且 owner 有自己的重试语义,
+ // 不能代它重放(会双跑或空转);仍要学习并关掉旧 runtime。
+ const dispatched = { ...msg('user', '{"orcaSource":"lead","content":"do it"}', 'u1', 1),
+ agentMeta: { origin: { kind: 'orca' } } };
+ const deps = makePiDeps([dispatched]);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(
+ rollover.tryRecover('s1', { ...receipt, reason: 'unsupported-request-option', message: rejection }),
+ ).resolves.toBe(false);
+ expect(deps.recordPiNativeCompatOverride).toHaveBeenCalledWith(
+ 'opencode-go',
+ 'glm-5.3-flash',
+ { supportsLongCacheRetention: false },
+ 'a'.repeat(64),
+ );
+ expect(deps.closeSession).toHaveBeenCalledWith('s1');
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ expect(deps.onRebuilt).not.toHaveBeenCalled();
+ // Persist before retiring the runtime: failed writes must leave it intact.
+ expect(deps.recordPiNativeCompatOverride.mock.invocationCallOrder[0]).toBeLessThan(
+ deps.closeSession.mock.invocationCallOrder[0],
+ );
+ });
+
+ it('learns the fix but leaves replay to a headless/bound owner', async () => {
+ const deps = makePiDeps([msg('user', '继续', 'u1', 1)]);
+ deps.hasExternalRecoveryOwner.mockReturnValue(true);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(
+ rollover.tryRecover('s1', { ...receipt, reason: 'unsupported-request-option', message: rejection }),
+ ).resolves.toBe(false);
+ expect(deps.recordPiNativeCompatOverride).toHaveBeenCalledOnce();
+ expect(deps.closeSession).toHaveBeenCalledWith('s1');
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ });
+
+ it('preserves external ownership released during terminal processing', async () => {
+ const deps = makePiDeps([msg('user', '继续', 'u1', 1)]);
+ deps.hasExternalRecoveryOwner.mockReturnValue(true);
+ deps.drainPersistQueue.mockImplementation(async () => {
+ deps.hasExternalRecoveryOwner.mockReturnValue(false);
+ });
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(rollover.tryRecover('s1', {
+ ...receipt, reason: 'unsupported-request-option', message: rejection,
+ })).resolves.toBe(false);
+ expect(deps.recordPiNativeCompatOverride).toHaveBeenCalledOnce();
+ expect(deps.closeSession).toHaveBeenCalledWith('s1');
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ });
+
+ it('does not replay when the learned override never reached disk', async () => {
+ // 存储返回 false(键不合法/磁盘失败)时不能重放:闩锁永远为假,会无限重试同一个 400。
+ const deps = makePiDeps([msg('user', '再跑一遍', 'u2', 1)]);
+ deps.recordPiNativeCompatOverride.mockResolvedValue(false);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(
+ rollover.tryRecover('s1', { ...receipt, reason: 'unsupported-request-option', message: rejection }),
+ ).resolves.toBe(false);
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ expect(deps.onRebuilt).not.toHaveBeenCalled();
+ });
+
+ it('does not replay when persisting the learned override throws', async () => {
+ const deps = makePiDeps([msg('user', '再跑一遍', 'u2', 1)]);
+ deps.recordPiNativeCompatOverride.mockRejectedValue(new Error('disk full'));
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+
+ await expect(
+ rollover.tryRecover('s1', { ...receipt, reason: 'unsupported-request-option', message: rejection }),
+ ).resolves.toBe(false);
+ expect(deps.replayUserMessage).not.toHaveBeenCalled();
+ });
+
+ it('drops a repeated terminal error after the self-heal already replayed the turn', async () => {
+ const deps = makePiDeps([msg('user', '再跑一遍', 'u2', 1)]);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+ await expect(
+ rollover.tryRecover(
+ 's1',
+ { ...receipt, reason: 'unsupported-request-option', message: rejection },
+ { instanceId: 'inst-1', generation: 1 },
+ ),
+ ).resolves.toBe(true);
+ expect(deps.replayUserMessage).toHaveBeenCalledTimes(1);
+
+ // 同一轮重复终态 error(此时历史里已有重放产出的 assistant):直接丢弃,
+ // 不再 surface —— 否则已自动续跑的任务里会挂一张 400 错误卡。
+ deps.listMessages.mockResolvedValue([
+ msg('user', '再跑一遍', 'u2', 1),
+ msg('assistant', '已经回复过了', 'a1', 2),
+ ]);
+ rollover.claim('s1');
+ await expect(
+ rollover.tryRecover(
+ 's1',
+ { ...receipt, reason: 'unsupported-request-option', message: rejection },
+ { instanceId: 'inst-1', generation: 1 },
+ ),
+ ).resolves.toBe(true);
+ expect(deps.replayUserMessage).toHaveBeenCalledTimes(1);
+ expect(deps.onRebuilt).toHaveBeenCalledTimes(1);
+ });
+
+ it('surfaces a same-signature failure from the replayed turn (new turn identity)', async () => {
+ // 重放产生的新一轮失败必须如实上报:不能因为 clientId 相同就被当成旧终态的重复投递。
+ const deps = makePiDeps([msg('user', '再跑一遍', 'u2', 1)]);
+ const rollover = createContextOverflowRollover(deps);
+ rollover.claim('s1');
+ await expect(
+ rollover.tryRecover(
+ 's1',
+ { ...receipt, reason: 'unsupported-request-option', message: rejection },
+ { instanceId: 'inst-1', generation: 1 },
+ ),
+ ).resolves.toBe(true);
+
+ deps.listMessages.mockResolvedValue([
+ msg('user', '再跑一遍', 'u2', 1),
+ msg('assistant', '重放又失败了', 'a1', 2),
+ ]);
+ rollover.claim('s1');
+ await expect(
+ rollover.tryRecover(
+ 's1',
+ { ...receipt, reason: 'unsupported-request-option', message: rejection },
+ { instanceId: 'inst-2', generation: 2 },
+ ),
+ ).resolves.toBe(false);
+ expect(deps.replayUserMessage).toHaveBeenCalledTimes(1);
+ });
+ });
+
it('rebuilds scheduler/IM turns without generic replay so the owner retries', async () => {
const deps = makeDeps([
{
@@ -1886,4 +2280,3 @@ describe('withReplaySourceNotes', () => {
).toBe('继续');
});
});
-
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/sessionEventPipeline.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/sessionEventPipeline.test.ts
index 72438105d1..b03cd1c2e7 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/sessionEventPipeline.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/sessionEventPipeline.test.ts
@@ -737,6 +737,74 @@ describe('production Session event pipeline', () => {
await h.dispose();
});
+ it('keeps a compat self-heal error off the wire while the rollover recovers', async () => {
+ const h = harness();
+ h.activity.setSessionInTurn('task', true);
+ const tryRecover = vi.fn(async () => true);
+ (h.deps as { contextOverflowRolloverHolder: unknown }).contextOverflowRolloverHolder = {
+ claim: vi.fn(() => 'claimed' as const),
+ tryRecover,
+ };
+ h.emit(event('error', {
+ reason: 'unsupported-request-option',
+ message: '400: {"param":"prompt_cache_retention","type":"invalid_request_error"}',
+ }));
+ // 生产路径:claim 成立 → 广播被压住,自愈成功后直接丢弃(不闪错误横幅)。
+ expect(tryRecover).toHaveBeenCalledWith(
+ 'task',
+ expect.objectContaining({ reason: 'unsupported-request-option' }),
+ { instanceId: undefined, generation: undefined },
+ );
+ expect(effects.fn('broadcast')).not.toHaveBeenCalled();
+ await Promise.resolve();
+ await Promise.resolve();
+ expect(h.deps.overflowSuppressedBroadcasts.size).toBe(0);
+ await h.dispose();
+ });
+
+ it('flushes a suppressed compat error when no rollover owner can surface it', async () => {
+ const h = harness();
+ h.activity.setSessionInTurn('task', true);
+ h.emit(event('error', {
+ reason: 'unsupported-request-option',
+ message: '400: {"param":"prompt_cache_retention","type":"invalid_request_error"}',
+ }));
+ // holder 未装配(claim=idle):投递层压住的广播必须在终态层补出去,
+ // 否则错误行写了但用户看不到横幅,map 条目也永不清理。
+ expect(effects.fn('broadcast')).toHaveBeenCalledWith(
+ 'maker:event',
+ expect.objectContaining({ persistId: undefined }),
+ );
+ expect(h.deps.overflowSuppressedBroadcasts.size).toBe(0);
+ await h.dispose();
+ });
+
+ it('does not flush a stale suppressed error onto a later unrelated error', async () => {
+ const h = harness();
+ h.activity.setSessionInTurn('task', true);
+ // turn A:autoResume 接管窗口内,投递层压住广播且 idle 分支被跳过 → 条目留在 map。
+ const coordinator = h.deps.agentInputCoordinatorHolder as {
+ isAutoResumeDeferred: ReturnType<typeof vi.fn>;
+ };
+ coordinator.isAutoResumeDeferred.mockReturnValue(true);
+ h.emit(event('error', {
+ reason: 'unsupported-request-option',
+ message: '400: {"param":"prompt_cache_retention","type":"invalid_request_error"}',
+ }));
+ expect(h.deps.overflowSuppressedBroadcasts.size).toBe(1);
+
+ // turn B:普通终态 error,与 A 无关。
+ coordinator.isAutoResumeDeferred.mockReturnValue(false);
+ h.emit(event('error', { message: 'boom', reason: 'sdk_crash' }));
+ // A 不得被当成 B 播出去(否则横幅文案与错误行对不上);过期条目直接丢弃。
+ expect(h.deps.overflowSuppressedBroadcasts.size).toBe(0);
+ expect(effects.fn('broadcast')).toHaveBeenCalled();
+ for (const call of effects.fn('broadcast').mock.calls) {
+ expect(JSON.stringify(call[1])).not.toContain('prompt_cache_retention');
+ }
+ await h.dispose();
+ });
+
it.each([true, false])(
'rechecks recovery after delivery changes pending to %s',
async (pendingAfter) => {
diff --git a/apps/desktop/src/main/maker-ipc/contextOverflowRollover.ts b/apps/desktop/src/main/maker-ipc/contextOverflowRollover.ts
index 098c5d4d9b..4952f1c608 100644
--- a/apps/desktop/src/main/maker-ipc/contextOverflowRollover.ts
+++ b/apps/desktop/src/main/maker-ipc/contextOverflowRollover.ts
@@ -9,9 +9,13 @@ import {
CODEX_HISTORY_OVERSIZED_REASON,
CONTEXT_OVERFLOW_REASON,
PI_REQUEST_BODY_RECOVERY_EXHAUSTED,
+ type PiCacheCompatibility,
isContextOverflowErrorMessage,
isDeterministicHostCompactFailure,
isRemoteCompactEncryptedContentError,
+ isUnsupportedRequestOptionErrorMessage,
+ unsupportedRequestOptionCompatOverride,
+ UNSUPPORTED_REQUEST_OPTION_REASON,
} from '@cindy/maker-core';
import {
projectAgentFacingText,
@@ -96,6 +100,28 @@ function isCompanionCompactFailure(data: unknown): boolean {
&& isDeterministicHostCompactFailure(value.replace(/error running remote compact task/ig, 'Error during compaction')));
}
+/**
+ * 上游拒收「可选请求增强字段」的终态错误(PI 专属自愈对象)。
+ * 只认结构化 reason,或「被点名缓存字段 + 明确拒收关系」的错误文案;
+ * 普通 400 / 鉴权失败不满足,不得拿来自愈。
+ */
+export function isUnsupportedRequestOptionErrorData(data: unknown): boolean {
+ if (!data || typeof data !== 'object') return false;
+ const rec = data as { reason?: unknown; message?: unknown; sdkError?: unknown };
+ if (rec.reason === UNSUPPORTED_REQUEST_OPTION_REASON) return true;
+ return [rec.message, rec.sdkError].some(
+ (value) => typeof value === 'string' && isUnsupportedRequestOptionErrorMessage(value),
+ );
+}
+
+function unsupportedRequestOptionErrorText(data: unknown): string {
+ if (!data || typeof data !== 'object') return '';
+ const rec = data as { message?: unknown; sdkError?: unknown };
+ return [rec.message, rec.sdkError].find(
+ (value): value is string => typeof value === 'string' && value.length > 0,
+ ) ?? '';
+}
+
export interface NativeSessionRecoveryTarget {
model: string;
providerId: string | null;
@@ -409,6 +435,8 @@ export interface ContextOverflowRolloverDeps {
sessionId: string,
): Promise<{ reason?: string; sourceUserClientId?: string | null } | null>;
getLiveSession(sessionId: string): {
+ readonly instanceId?: string;
+ getTurnGeneration?(): number;
isTurnRunning(): boolean;
listBackgroundTasks?(): ReadonlyArray<unknown>;
getUsageSnapshot?(): { contextTokens: number; contextWindow: number; needsRollover?: boolean };
@@ -439,12 +467,30 @@ export interface ContextOverflowRolloverDeps {
recovery?: { signal?: AbortSignal; continueFromHistory?: false } | {
signal?: AbortSignal;
continueFromHistory: true;
+ piCacheCompatibility?: PiCacheCompatibility;
sourceUserContent: unknown;
sourceUserClientId: string;
sourceCapabilitySelectionText: string;
},
): Promise<{ accepted: boolean }>;
getRecoveryAbortSignal?(sessionId: string): AbortSignal;
+ /**
+ * Read persisted learning for the exact connection/wire-model/route.
+ * A live runtime receipt separately confirms whether it actually loaded the fix.
+ */
+ readPiNativeCompatOverride?(
+ providerId: string,
+ modelId: string,
+ routeKey?: string,
+ ): Record<string, unknown> | undefined;
+ /** PI provider compat 自愈:把本次学习到的 compat 修正落盘,供重建的 models.json 合并。
+ * 返回 true 仅当条目确实落盘;false 时调用方不得重放(否则闩锁永远是假、无限重试)。 */
+ recordPiNativeCompatOverride?(
+ providerId: string,
+ modelId: string,
+ compat: Record<string, unknown>,
+ routeKey?: string,
+ ): Promise<boolean> | boolean;
/** Synchronous: external dispatch may release its turn marker on this same terminal event. */
hasExternalRecoveryOwner?(sessionId: string): boolean;
onRebuilt?(sessionId: string): void;
@@ -509,7 +555,12 @@ export function shouldRebuildForModelWindowSwitch(input: {
export function createContextOverflowRollover(deps: ContextOverflowRolloverDeps): {
claim(sessionId: string): OverflowClaimResult;
cancelRecovery(sessionId: string): void;
- tryRecover(sessionId: string, errorData: unknown): Promise<boolean>;
+ tryRecover(
+ sessionId: string,
+ errorData: unknown,
+ /** 产生该终态错误的 turn 身份:区分「同一轮的重复投递」与「重放后的新一轮失败」。 */
+ turnIdentity?: { instanceId?: string; generation?: number },
+ ): Promise<boolean>;
prepareUnhealthySession(sessionId: string): Promise<boolean>;
prepareNativeSessionRecovery(
sessionId: string,
@@ -533,21 +584,35 @@ export function createContextOverflowRollover(deps: ContextOverflowRolloverDeps)
const inFlight = new Map<string, AbortController | undefined>();
// One automatic continuation per source input, not one per replacement thread.
const continuedInputs = new Map<string, string>();
+ // 自愈成功时那一轮的 turn 身份:同身份再次到达 = 同一轮的重复终态投递(丢弃);
+ // 新身份 = 重放后的新一轮失败(必须 surface,不能静默吞掉)。
+ const healedCompatTurns = new Map<string, { instanceId?: string; generation?: number }>();
+ /**
+ * (会话, provider, model) 已经用「已学覆盖」重建过:再失败就不再自动重建,交常规
+ * 错误面。必须带上 pair:同一会话换模型后,旧模型的记录不能挡住新模型的自愈。
+ */
+ const rebuiltWithLearnedCompat = new Set<string>();
const runRecover = async (
sessionId: string,
errorData: unknown,
signal?: AbortSignal,
+ turnIdentity?: { instanceId?: string; generation?: number },
+ externalOwnerAtFailure = false,
): Promise<boolean> => {
if (signal?.aborted) return true;
const oversized = isOversizedHistoryErrorData(errorData);
- if (!isContextOverflowErrorData(errorData) && !oversized) return false;
+ const unsupportedOption = isUnsupportedRequestOptionErrorData(errorData);
+ if (!isContextOverflowErrorData(errorData) && !oversized && !unsupportedOption) return false;
await deps.drainPersistQueue();
const sessionRow = await deps.getSessionRow(sessionId);
signal?.throwIfAborted();
if (!sessionRow || sessionRow.status === 'deleted') return false;
// SSH only. device-link 会话落在被控桌面本地库,没有 remoteHostId,必须继续换窗。
if (sessionRow.remoteHostId) return false;
+ // compat 自愈只服务本机桌面会话(与 replayUserMessage 的 continueFromHistory 一致):
+ // 外部派单方有自己的重试语义,canonical bot 的派单走 owner 路径,不在这里代播。
+ if (unsupportedOption && (sessionRow.source !== 'desktop' || sessionRow.agentKind !== 'pi')) return false;
if (oversized && (!canContinueContextRecovery(sessionRow) || sessionRow.agentKind !== 'codex')) return false;
return deps.withCloseSuppressed(sessionId, async () => {
@@ -559,6 +624,137 @@ export function createContextOverflowRollover(deps: ContextOverflowRolloverDeps)
const tokens: 'violated' | 'unknown' = isContextOverflowErrorData(errorData)
? 'violated'
: 'unknown';
+ // ── PI provider compat 自愈:上游拒收可选请求字段(如 prompt_cache_retention)──
+ // 失败轮零产出,学习该 provider/model 的 compat 修正后关会话重建(新 models.json
+ // 不再带该字段),并重放同一轮用户消息。只做一次:已学过的 (provider, model)
+ // 再失败就交给常规错误面,绝不循环重试。
+ if (unsupportedOption) {
+ if (!live && turnIdentity?.instanceId) return false;
+ const compat = unsupportedRequestOptionCompatOverride(
+ unsupportedRequestOptionErrorText(errorData),
+ );
+ const receipt = (errorData as { piCacheCompatibility?: PiCacheCompatibility }).piCacheCompatibility;
+ const providerId = receipt?.providerId;
+ const modelId = receipt?.wireModelId;
+ if (!receipt || !/^[a-f0-9]{64}$/.test(receipt.routeKey)
+ || receipt.providerId !== sessionRow.providerId || receipt.modelId !== sessionRow.model) return false;
+ // providerId 为 null(老会话/远端控制端未持久化)时无法确定学习键,不自愈。
+ if (!compat || !providerId || !modelId || !deps.recordPiNativeCompatOverride) {
+ return false;
+ }
+ const source = await deps.listMessages(sessionId);
+ signal?.throwIfAborted();
+ const plan = planContextOverflowRollover(source, continuedInputs.get(sessionId));
+ // 同一轮重复终态 error:上一次自愈已经重放并续跑过,这次直接丢弃(不重放、
+ // 不落错误行)。必须用「实例 + 轮次」身份区分:重放失败是新一轮(新 instanceId /
+ // 新 generation),必须照常 surface,否则真实的重试失败会被静默吞掉。
+ const sourceUser =
+ plan.action === 'rebuild'
+ ? { clientId: plan.sourceUserClientId }
+ : [...source].reverse().find((message) => message.role === 'user' && !isSyntheticUser(message));
+ const healedTurn = healedCompatTurns.get(sessionId);
+ if (
+ sourceUser &&
+ healedTurn?.generation !== undefined &&
+ healedTurn.generation === turnIdentity?.generation &&
+ healedTurn.instanceId === turnIdentity?.instanceId &&
+ continuedInputs.get(sessionId) === sourceUser.clientId
+ ) {
+ return true;
+ }
+ // A late terminal event must not retire a new runtime or a later turn.
+ const sourceGeneration = live?.getTurnGeneration?.();
+ const sourceUnchanged = () => {
+ const currentLive = deps.getLiveSession(sessionId);
+ return currentLive?.instanceId === live?.instanceId
+ && currentLive?.getTurnGeneration?.() === sourceGeneration
+ && (!turnIdentity?.instanceId || !currentLive?.instanceId || turnIdentity.instanceId === currentLive.instanceId)
+ && (turnIdentity?.generation === undefined || !currentLive?.getTurnGeneration || turnIdentity.generation === currentLive.getTurnGeneration())
+ && !currentLive?.isTurnRunning()
+ && !(currentLive?.listBackgroundTasks?.().length);
+ };
+ if (!sourceUnchanged()) return false;
+ const learnedBefore = deps.readPiNativeCompatOverride?.(providerId, modelId, receipt.routeKey) ?? false;
+ const rebuiltKey = JSON.stringify([sessionId, providerId, modelId, receipt.routeKey]);
+ // 磁盘上已学过(别的会话先学到、或用户在别处修好)时,还要区分「已学过」和
+ // 「当前 runtime 已应用」:启动时 models.json 里没有该覆盖的旧 runtime 仍然会一直
+ // 400,普通发送不会刷新模型配置,所以这里要允许它应用覆盖并重建一次。已经用覆盖
+ // 重建过的 runtime 再收到同一类 400 说明覆盖没解决问题,直接交常规错误面,绝不
+ // 反复 close/重放。判据按 pair 记:换过模型的会话不能被旧模型的记录挡住。
+ if (receipt.applied || (learnedBefore && rebuiltWithLearnedCompat.has(rebuiltKey))) {
+ return false;
+ }
+ // 外部派单方(Orca / scheduler / IM / ghost setup)拥有自己的重试语义:不能代它
+ // 重放用户消息 —— 派单正文经 wire 投影可能退化为空,重复发送还可能让两方各跑一次。
+ const externalOwner =
+ externalOwnerAtFailure || (plan.action !== 'stop' &&
+ (plan.skipGenericReplay || (deps.hasExternalRecoveryOwner?.(sessionId) ?? false)));
+ // Saving is independent of replay: preserve valid learning even for owner-managed turns.
+ const learned = learnedBefore || await deps.recordPiNativeCompatOverride(providerId, modelId, compat, receipt.routeKey);
+ signal?.throwIfAborted();
+ if (!learned || !sourceUnchanged()) return false;
+ const current = await deps.getSessionRow(sessionId);
+ signal?.throwIfAborted();
+ if (!current || current.status !== 'active' || current.clearedAt !== sessionRow.clearedAt
+ || current.providerId !== receipt.providerId || current.model !== receipt.modelId) return false;
+ const currentMessages = await deps.listMessages(sessionId);
+ signal?.throwIfAborted();
+ const latestUser = [...currentMessages].reverse().find((message) => message.role === 'user' && !isSyntheticUser(message));
+ if (!sourceUnchanged() || latestUser?.clientId !== sourceUser?.clientId) return false;
+ // Retire the idle stale runtime so the next owner-managed send loads the fix.
+ if (live) await deps.closeSession(sessionId);
+ signal?.throwIfAborted();
+ // The Pi receipt also covers output not yet flushed to the desktop database.
+ if (plan.action === 'stop' || externalOwner
+ || (errorData as { piCacheRecoverySafe?: boolean }).piCacheRecoverySafe !== true) {
+ return false;
+ }
+ // Consume before any async close/replay; an error cannot re-arm this input.
+ continuedInputs.set(sessionId, plan.sourceUserClientId);
+ rebuiltWithLearnedCompat.add(rebuiltKey);
+ signal?.throwIfAborted();
+ const sourceWire = persistedUserContentToWireMessage(
+ plan.sourceUserAgentFacingWireContent ?? plan.sourceUserContent,
+ );
+ const sourceText = typeof sourceWire === 'string' ? sourceWire : sourceWire.content;
+ const replay = await deps.replayUserMessage(
+ sessionId,
+ plan.sourceUserContent,
+ plan.sourceUserAgentFacingWireContent,
+ {
+ signal,
+ // 保留同一 Pi 会话历史:失败轮的 error assistant 会被 pi-ai 序列化时
+ // 跳过,模型看到的仍是同一条用户请求,重放即重试。
+ continueFromHistory: true,
+ piCacheCompatibility: receipt,
+ sourceUserContent: plan.sourceUserContent,
+ sourceUserClientId: plan.sourceUserClientId,
+ sourceCapabilitySelectionText:
+ typeof sourceText === 'string' ? sourceText : extractPlainText(sourceText),
+ },
+ );
+ signal?.throwIfAborted();
+ if (!replay.accepted) {
+ deps.log.warn('pi provider compat replay was not accepted', {
+ sessionId,
+ providerId,
+ modelId,
+ });
+ return false;
+ }
+ deps.onRebuilt?.(sessionId);
+ continuedInputs.set(sessionId, plan.sourceUserClientId);
+ if (turnIdentity?.generation !== undefined) {
+ healedCompatTurns.set(sessionId, turnIdentity);
+ }
+ deps.log.info('pi provider compat learned; replayed the user message', {
+ sessionId,
+ providerId,
+ modelId,
+ compat,
+ });
+ return true;
+ }
const action = decideCindyCompression({
local: true,
bytes: oversized ? 'violated' : 'unknown',
@@ -1005,20 +1201,30 @@ export function createContextOverflowRollover(deps: ContextOverflowRolloverDeps)
inFlight.get(sessionId)?.abort();
},
- async tryRecover(sessionId: string, errorData: unknown): Promise<boolean> {
+ async tryRecover(
+ sessionId: string,
+ errorData: unknown,
+ turnIdentity?: { instanceId?: string; generation?: number },
+ ): Promise<boolean> {
let signal: AbortSignal | undefined;
try {
// IM may not persist this input (protected content), and an attached IM
// turn can outlive its binding. Check live ownership before any await.
if (isOversizedHistoryErrorData(errorData) && deps.hasExternalRecoveryOwner?.(sessionId)) return false;
+ // Terminal subscribers may release a headless/IM marker immediately.
+ // Keep learning, but never take over that turn's replay after an await.
+ const externalOwnerAtFailure = isUnsupportedRequestOptionErrorData(errorData)
+ && (deps.hasExternalRecoveryOwner?.(sessionId) ?? false);
const claim = inFlight.get(sessionId) ?? new AbortController();
inFlight.set(sessionId, claim);
const inputSignal = deps.getRecoveryAbortSignal?.(sessionId);
signal = inputSignal ? AbortSignal.any([claim.signal, inputSignal]) : claim.signal;
if (deps.withSessionLock) {
- return await deps.withSessionLock(sessionId, () => runRecover(sessionId, errorData, signal));
+ return await deps.withSessionLock(sessionId, () =>
+ runRecover(sessionId, errorData, signal, turnIdentity, externalOwnerAtFailure),
+ );
}
- return await runRecover(sessionId, errorData, signal);
+ return await runRecover(sessionId, errorData, signal, turnIdentity, externalOwnerAtFailure);
} catch (error) {
if (signal?.aborted) return true;
deps.log.warn('context overflow rollover failed', {
diff --git a/apps/desktop/src/main/maker-ipc/makerSendTransaction.ts b/apps/desktop/src/main/maker-ipc/makerSendTransaction.ts
index 6909ed035d..e892ad0971 100644
--- a/apps/desktop/src/main/maker-ipc/makerSendTransaction.ts
+++ b/apps/desktop/src/main/maker-ipc/makerSendTransaction.ts
@@ -1,5 +1,6 @@
import type { AutoReviewUserIntent } from '@cindy/maker-core';
import {
+ PI_CACHE_RECOVERY_EXPECTATION,
CodexResumePreparationBlockedError,
AUTO_REVIEW_SOURCE_CONTENT,
AUTO_REVIEW_USER_INTENT,
@@ -245,6 +246,7 @@ export function revokeTrustedDesktopQueuedOrigin(item: AgentInputQueuedMessage):
}
type MakerSendOptions = {
+ readonly [PI_CACHE_RECOVERY_EXPECTATION]?: import('@cindy/maker-core').SendOptions[typeof PI_CACHE_RECOVERY_EXPECTATION];
readonly [AUTO_REVIEW_DELEGATED_CONTINUATION]?: true;
retryUserClientId?: string;
toolsDisabled?: boolean;
@@ -1574,6 +1576,7 @@ export function createMakerSendTransaction(deps: MakerSendTransactionDeps): Make
...(so.toolsDisabled === true ? { toolsDisabled: true } : {}),
turnAttemptToken: so.turnAttemptToken,
signal: so.signal,
+ [PI_CACHE_RECOVERY_EXPECTATION]: so[PI_CACHE_RECOVERY_EXPECTATION],
...(so.onVendorTurnReserved ? { onTurnReserved: so.onVendorTurnReserved } : {}),
// scheduler 排队消息:origin 打到本轮 turnOrigin(IM 转播识别自动 turn),
// 与 runner 直发路径的 session.send({ origin }) 语义对齐。
diff --git a/apps/desktop/src/main/maker-ipc/register.ts b/apps/desktop/src/main/maker-ipc/register.ts
index c7aede1230..2d6bf28648 100644
--- a/apps/desktop/src/main/maker-ipc/register.ts
+++ b/apps/desktop/src/main/maker-ipc/register.ts
@@ -122,7 +122,10 @@ import {
listPiSubagentRuns,
piSubagentRunRoot,
} from '@cindy/maker-core/pi-subagent-runs';
-import { AUTO_REVIEW_SOURCE_CONTENT, AUTO_REVIEW_USER_INTENT, INHERITED_CAPABILITY_SELECTION, MAIN_OWNED_SEND_CONTEXT } from '@cindy/maker-core';
+import {
+ PI_CACHE_RECOVERY_EXPECTATION, AUTO_REVIEW_SOURCE_CONTENT, AUTO_REVIEW_USER_INTENT,
+ INHERITED_CAPABILITY_SELECTION, MAIN_OWNED_SEND_CONTEXT,
+} from '@cindy/maker-core';
import { AUTO_REVIEW_DELEGATED_CONTINUATION, readAutoReviewUserText, restoreAutoReviewSteerIntent, restoreAutoReviewUserIntent } from './autoReviewUserIntent.js';
import type {
AgentEvent,
@@ -1008,6 +1011,10 @@ import {
classifyCodexHistoryOversized,
reserveCodexForkCleanup,
} from '../maker-host/codex-local-sessions.js';
+import {
+ readPiNativeCompatOverride,
+ recordPiNativeCompatOverride,
+} from '../maker-host/pi-native-compat-overrides-store.js';
import { readCodexThreadStorageReadOnly } from '../maker-host/codex-thread-storage.js';
import { hydrateQueuedAgentReferences } from './agentInputReferences.js';
import { agentHandoffPending } from './agentHandoffPendingSingleton.js';
@@ -16410,6 +16417,12 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
}
return coordinator.getInputAbortSignal(sessionId);
},
+ // PI provider compat 自愈:上游拒收可选请求字段后,把「该 provider/model 关掉该字段」
+ // 学进 models.json compat 的覆盖存储;重建会话时 writeModelsJson 合并它。
+ readPiNativeCompatOverride: (providerId, modelId, routeKey) =>
+ readPiNativeCompatOverride(providerId, modelId, routeKey),
+ recordPiNativeCompatOverride: async (providerId, modelId, compat, routeKey) =>
+ recordPiNativeCompatOverride(providerId, modelId, compat, routeKey),
replayUserMessage: async (sessionId, content, agentFacingWireContent, recovery) => {
const [row] = await getDbClient()
.drizzle.select()
@@ -16466,6 +16479,8 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
recovery?.continueFromHistory
? {
signal: recovery.signal,
+ [PI_CACHE_RECOVERY_EXPECTATION]: recovery.piCacheCompatibility,
+ ...(recovery.piCacheCompatibility ? { retryUserClientId: recovery.sourceUserClientId } : {}),
[INHERITED_CAPABILITY_SELECTION]: recovery.sourceCapabilitySelectionText,
// The internal continuation is not fresh user authorization. Restore
// intent from authored history, never attachment/quote projections.
diff --git a/apps/desktop/src/main/maker-ipc/sessionEventDelivery.ts b/apps/desktop/src/main/maker-ipc/sessionEventDelivery.ts
index 41392094ee..b7df7539f4 100644
--- a/apps/desktop/src/main/maker-ipc/sessionEventDelivery.ts
+++ b/apps/desktop/src/main/maker-ipc/sessionEventDelivery.ts
@@ -8,6 +8,7 @@ import { type OrcaTeamService } from './orcaTeamService.js';
import {
isContextOverflowErrorData,
isOversizedHistoryErrorData,
+ isUnsupportedRequestOptionErrorData,
} from './contextOverflowRollover.js';
import { noteClaudeSessionTurnState } from '../maker-host/claude-session-background-activity.js';
import { DeferredCodexRestartService } from './deferredCodexRestart.js';
@@ -99,7 +100,12 @@ export function deliverSessionEvent(
!session.remoteHostId &&
event.type === 'error' &&
isTerminalTurnErrorEvent(event) &&
- (isContextOverflowErrorData(event.data) || isOversizedHistoryErrorData(event.data));
+ (isContextOverflowErrorData(event.data) ||
+ isOversizedHistoryErrorData(event.data) ||
+ // 与 sessionEventTerminal 的 overflowClaim 判据保持一致:PI compat 自愈的终态错误
+ // 也要先压住广播并预留 persistId,否则自愈失败时 surfaceOverflowFailure 拿不到
+ // 预留 id(dedup 已被吃掉),错误行不落库、后台任务历史里看不到失败。
+ isUnsupportedRequestOptionErrorData(event.data));
// 供应商组正在为这次失败换电脑:error 行先不落库(暂存,换成了就丢掉),同样不预留 persistId。
// 协调器在 prepare 阶段同步登记,结算都是异步的,这里与 terminal 阶段看到的是同一次登记。
const providerGroupHoldId =
diff --git a/apps/desktop/src/main/maker-ipc/sessionEventTerminal.ts b/apps/desktop/src/main/maker-ipc/sessionEventTerminal.ts
index 1394048005..426611e418 100644
--- a/apps/desktop/src/main/maker-ipc/sessionEventTerminal.ts
+++ b/apps/desktop/src/main/maker-ipc/sessionEventTerminal.ts
@@ -38,6 +38,7 @@ import {
createContextOverflowRollover,
isContextOverflowErrorData,
isOversizedHistoryErrorData,
+ isUnsupportedRequestOptionErrorData,
} from './contextOverflowRollover.js';
import { isTerminalTurnErrorEvent } from './sessionTurnActivityTracker.js';
import { botGroupRuntimeFailureCode } from './botGroupRuntimeFailure.js';
@@ -155,6 +156,7 @@ export function finishSessionTerminalEvent(
const {
event,
attributedEvent,
+ broadcastEvent,
eventAgentMeta,
isContinuationBoundary,
isPlannedUpgradeClose,
@@ -298,7 +300,8 @@ export function finishSessionTerminalEvent(
!isGatewayProxyTokenRecovery &&
!autoResumeSuppressesPersist &&
(isContextOverflowErrorData(attributedEvent.data) ||
- isOversizedHistoryErrorData(attributedEvent.data))
+ isOversizedHistoryErrorData(attributedEvent.data) ||
+ isUnsupportedRequestOptionErrorData(attributedEvent.data))
? (deps.contextOverflowRolloverHolder?.claim(session.id) ?? 'idle')
: 'idle';
const deferUnsuccessfulProductTurn = (): void => {
@@ -354,7 +357,10 @@ export function finishSessionTerminalEvent(
notifyUnsuccessfulProductTurn();
};
void deps.contextOverflowRolloverHolder
- ?.tryRecover(session.id, overflowErrorData)
+ ?.tryRecover(session.id, overflowErrorData, {
+ instanceId: event.sessionInstanceId,
+ generation: event.sessionTurnGeneration,
+ })
.then((recovered) => {
if (recovered) {
deps.overflowSuppressedBroadcasts.delete(session.id);
@@ -379,6 +385,20 @@ export function finishSessionTerminalEvent(
!isGatewayProxyTokenRecovery &&
!autoResumeSuppressesPersist
) {
+ // 投递层为 overflow/oversized/compat 终态错误压住了广播;走到这里说明没有 claim
+ // owner(rollover holder 未装配)会去 surface/丢弃它。补出广播,否则错误行写了
+ // 但用户看不到横幅,且 map 里的条目永不清理。
+ const stashed = deps.overflowSuppressedBroadcasts.get(session.id);
+ if (stashed) {
+ deps.overflowSuppressedBroadcasts.delete(session.id);
+ // 只补当前事件的广播:stash 按 session 索引,可能残留更早 turn 的条目(例如
+ // autoResume 压住、owner 路径不碰这个 map 的情形)。把过期事件盖着当前 persistId
+ // 播出去会让横幅文案与错误行对不上;过期条目直接丢弃(它自己的 owner 已负责过它)。
+ if (stashed.event === broadcastEvent) {
+ deps.broadcastToAllWindows(MAKER_PUSH.EVENT, stashed);
+ deps.handleAgentIslandEventAfterBroadcast(session, stashed.event);
+ }
+ }
// 供应商组正在为这次失败换电脑:先不落库,换成了就丢掉,没换成再补落。登记期间到达的另一条不同错误
// 不归这次暂存,照常落库。
if (
diff --git a/docs/dev-rules/pi-harness.md b/docs/dev-rules/pi-harness.md
index dd0e952178..1af61acc38 100644
--- a/docs/dev-rules/pi-harness.md
+++ b/docs/dev-rules/pi-harness.md
@@ -437,8 +437,33 @@ Pi CLI 管理入口、内核自更新与旧工具兼容的执行边界见
`bypassPermissions` 的契约测试已补;Pi bridge 的 auto allow/deny 也用真二进制覆盖。
- [x] **resume 边界**:已用 Pi v0.82.1 真二进制创建 JSONL,再由 v0.83.0 恢复;
invalid resume 在适配层先校验文件存在并遵守 CAS,precise rewind/fork 后 resume 有真二进制测试。
-- [x] **prompt cache**:Pi 子进程默认注入 `PI_CACHE_RETENTION=long`;不支持的 provider
- 忽略该选项。已用 ChatGPT 订阅实例确认 `cacheRead` 命中会端到端落库与展示。
+- [x] **prompt cache**:Pi 子进程默认注入 `PI_CACHE_RETENTION=long`;明确拒收该可选字段的
+ provider 由 compat 自愈学习并关掉该字段(见下条)。已用 ChatGPT 订阅实例确认 `cacheRead`
+ 命中会端到端落库与展示。
+- [x] **provider compat 自愈**:上游以 `invalid_request_error` 明确拒收某个可选请求字段时
+ (已知形态:Console Go / OpenCode Zen-Go 的 GLM 上游拒收 `prompt_cache_retention`,提示改用
+ `prompt_cache_options`;自定义政企/内网网关只拒 `prompt_cache_key`
+ ,见 issue #5878),Pi translator 打稳定 reason `unsupported-request-option`。
+ 仅接受被点名字段与明确拒收关系;普通 400、鉴权、限流、其他参数错误不学习。
+ Desktop 先将 `supportsLongCacheRetention: false` 原子记入
+ `<userData>/pi-native-compat-overrides.json` 的 `routes` 表;键为 JSON 数组
+ `[连接 ID, wire 模型 ID, SHA256(协议 + 真实端点)]`,端点包含路径、端口、查询参数,
+ 不保存原始 URL 或错误正文。连接、端点或协议变化均不复用旧记录;无身份不学习,
+ 损坏文件保留原样且不授权恢复。未发布 #4791 的无端点记录无法精确归属,不自动套用。
+ 当前运行时另持有启动/原生 registry 刷新成功时的应用快照;磁盘已学习不代表旧进程
+ 已应用。成功落盘后仅退役空闲的旧实例,新进程重建 models.json 并校验同一路由已应用。
+ Pi 1.0.2 普通 URL 下 compat 会移除两字段,但 URL 含 api.openai.com 时 key 仍可发送;
+ 因此既有 before_provider_request hook 按私有运行时规则的 provider/model/baseUrl 精确
+ 删除这两个字段,其他路由保持原生行为。原生子代理冻结继承相同规则;刷新失败回滚
+ models/settings 与规则文件,不保留半套配置。
+ 自动恢复只对本地 `source=desktop` Pi:整轮无文字/思考/工具调用或执行,原输入仍是
+ 最新输入,实例/轮次未更换、未取消、未切路由且无外部恢复 owner。同一输入最多一次,
+ 必须存在原生 user entry,使用原生分支重试以保持一条有效输入;缺失 entry 或应用确认
+ 时直接失败,禁止追加重复输入。恢复后仍拒收正常报错,不循环、不自动扩展降级。
+ 外部派单可学习并退役空闲旧实例,重试由原 owner 负责;原生子代理继承已有学习但不将
+ 子错误归给父任务学习/重放。SSH 不消费本地记录;设备互联/手机控制本地桌面任务走同一
+ 宿主路径,无新 IPC/UI。恢复只影响出错任务的空闲 Pi 实例,不重启应用、连接或其它任务。
+ 删除精确记录并重新创建运行时可重新探测;无后台探测、无自动到期,避免恢复失败循环。
## 7. 上线后路线图(已与 Chris 对齐)
diff --git a/packages/maker-core/src/agents/base-agent.ts b/packages/maker-core/src/agents/base-agent.ts
index 1d23caac18..28848b2b0e 100644
--- a/packages/maker-core/src/agents/base-agent.ts
+++ b/packages/maker-core/src/agents/base-agent.ts
@@ -205,6 +205,8 @@ export interface PiNativeModelSpec {
api?: PiNativeApi;
/** Per-model native endpoint retained from PI's bundled provider table. */
baseUrl?: string;
+ /** Host-only identity for learned compatibility when baseUrl is a local auth proxy. */
+ cacheIdentityBaseUrl?: string;
/** Add a model missing from PI's bundled catalog while inheriting the provider's bundled API. */
catalogAddition?: boolean;
name?: string;
@@ -271,6 +273,8 @@ export interface PiNativeProviderSpec {
sourceProviderId?: string;
name: string;
baseUrl: string;
+ /** True upstream endpoint behind a local auth proxy; never serialized to models.json. */
+ cacheIdentityBaseUrl?: string;
/** BYOM provider default. Omitted only when inheriting PI's bundled provider catalog. */
api?: PiNativeApi;
/** Keep PI's bundled models and serialize only models carrying an explicit api override. */
@@ -900,6 +904,17 @@ export interface AgentDeps {
context?: { remote: boolean; runtimeBinaryPath?: string },
) => PiGatewayModelSpec | null | undefined;
+ /**
+ * Pi-only:host 已学到(自愈写入)的 per-model compat 覆盖。写 models.json 时
+ * 合并进该原生 provider 模型的 compat;undefined = 无覆盖。不改变路由与凭证,
+ * 只关掉上游已明确拒收的可选字段(如 supportsLongCacheRetention: false)。
+ */
+ resolvePiNativeCompatOverride?: (
+ providerId: string,
+ modelId: string,
+ routeKey?: string,
+ ) => Record<string, unknown> | undefined;
+
/**
* Host-provided capability descriptor additions.
*
@@ -2062,7 +2077,10 @@ export interface MainOwnedSendContext {
* Session.send / handle.send 的可选附加项。
* 缺省 / 不识别字段必须安全忽略。
*/
+export const PI_CACHE_RECOVERY_EXPECTATION = Symbol('pi-cache-recovery-expectation');
+
export interface SendOptions {
+ readonly [PI_CACHE_RECOVERY_EXPECTATION]?: import('./pi/cache-compatibility.js').PiCacheCompatibility;
readonly [ASYNC_QUESTION_ANSWER]?: true;
readonly [AUTO_REVIEW_SOURCE_CONTENT]?: UserMessage['content'];
readonly [AUTO_REVIEW_USER_INTENT]?: AutoReviewUserIntent;
diff --git a/packages/maker-core/src/agents/index.ts b/packages/maker-core/src/agents/index.ts
index ed222b18fa..9bb6ffae5e 100644
--- a/packages/maker-core/src/agents/index.ts
+++ b/packages/maker-core/src/agents/index.ts
@@ -88,6 +88,13 @@ export {
UPSTREAM_STREAM_INTERRUPTED_REASON,
isStreamInterruptedErrorMessage,
} from './shared/stream-interrupt-error.js';
+// 上游拒收「可选请求增强字段」(如 prompt_cache_retention)时的稳定 reason:
+// desktop 据此把该 provider/model 的 compat 修正写进 models.json 并重放一轮(自愈)。
+export {
+ UNSUPPORTED_REQUEST_OPTION_REASON,
+ isUnsupportedRequestOptionErrorMessage,
+ unsupportedRequestOptionCompatOverride,
+} from './shared/unsupported-request-option-error.js';
// 同上理由(同 bundle 直接复用,不造第三份):desktop 的中断自愈判据要认「网络到不了
// 上游」这一类 —— 那类同样是"连不上"而不是"请求有问题",续跑一次就能过去。
export { isNetworkishErrorMessage, PI_GATEWAY_DROP_REASON } from './shared/network-error.js';
@@ -143,3 +150,5 @@ export {
isClaudeProjectKeyExact,
findClaudeSessionJsonl,
} from './claude-code/claude-projects-fs.js';
+
+export type { PiCacheCompatibility } from './pi/cache-compatibility.js';
diff --git a/packages/maker-core/src/agents/pi/__tests__/cache-compatibility.integration.test.ts b/packages/maker-core/src/agents/pi/__tests__/cache-compatibility.integration.test.ts
new file mode 100644
index 0000000000..c9fcd92c84
--- /dev/null
+++ b/packages/maker-core/src/agents/pi/__tests__/cache-compatibility.integration.test.ts
@@ -0,0 +1,102 @@
+import { createServer } from 'node:http';
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { PiAgent } from '../index.js';
+import { PI_CACHE_RECOVERY_EXPECTATION, type AgentDeps, type AgentSessionHandle } from '../../base-agent.js';
+import type { AgentEvent } from '../../../types/events.js';
+import type { Logger } from '../../../interfaces/logger.js';
+import type { PiCacheCompatibility } from '../cache-compatibility.js';
+const binary = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../../apps/pi-bin', process.platform + '-' + process.arch, process.platform === 'win32' ? 'pi.exe' : 'pi');
+const logger: Logger = { trace() {}, debug() {}, info() {}, warn() {}, error() {}, fatal() {}, child: () => logger };
+
+describe.skipIf(!existsSync(binary))('Pi cache learning over real HTTP and native RPC', () => {
+ it.each(['normal', 'api.openai.com'])('rebuilds with a learned fix and preserves one active input: %s', async (suffix) => {
+ const root = mkdtempSync(path.join(os.tmpdir(), 'cindy-cache-integration-'));
+ const received: Array<Record<string, unknown>> = [];
+ let rejectCacheFields = true;
+ const gateway = createServer(async (req, res) => {
+ let body = '';
+ for await (const chunk of req) body += chunk;
+ const data = JSON.parse(body);
+ received.push(data);
+ if (rejectCacheFields && (data.prompt_cache_key !== undefined || data.prompt_cache_retention !== undefined)) {
+ res.writeHead(400, { 'content-type': 'application/json' });
+ res.end(JSON.stringify({ message: 'Validation: Unsupported parameter(s): prompt_cache_key', type: 'invalid_request_error' }));
+ return;
+ }
+ res.writeHead(200, { 'content-type': 'text/event-stream' });
+ res.end('data: ' + JSON.stringify({ id: 'one', choices: [{ index: 0, delta: { role: 'assistant', content: 'OK' }, finish_reason: null }] }) + '\n\n'
+ + 'data: ' + JSON.stringify({ id: 'one', choices: [{ index: 0, delta: {}, finish_reason: 'stop' }], usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 } }) + '\n\n'
+ + 'data: [DONE]\n\n');
+ });
+ let handle: AgentSessionHandle | undefined;
+ try {
+ await new Promise<void>((resolve) => gateway.listen(0, '127.0.0.1', resolve));
+ const address = gateway.address();
+ if (!address || typeof address === 'string') throw new Error('missing loopback listener');
+ let endpoint = 'http://127.0.0.1:' + address.port + '/' + suffix + '/v1';
+ let learned: PiCacheCompatibility | undefined;
+ const deps: AgentDeps = {
+ binaryPath: binary, logger,
+ auth: { getState: async () => ({ authenticated: true, identity: 'fixture', authSource: 'api-key' }), triggerLogin: async () => ({ authenticated: true }), logout: async () => {}, getAuthEnv: async () => ({}) },
+ runtimeConfig: { endpoint: 'http://127.0.0.1:0' },
+ resolvePiAgentHome: () => path.join(root, 'agent'),
+ resolvePiNativeProviders: async () => ({ providers: [{ id: 'strict', sourceProviderId: 'strict', name: 'Strict fixture', baseUrl: endpoint, api: 'openai-completions', modelIdAliases: { 'fixture-alias': 'fixture-public' }, models: [{ id: 'fixture-public', wireId: 'fixture', api: 'openai-completions', contextWindow: 32768, maxTokens: 100 }] }], env: {} }),
+ resolvePiNativeCompatOverride: (provider, model, route) => learned && provider === learned.providerId && model === learned.wireModelId && route === learned.routeKey ? { supportsLongCacheRetention: false } : undefined,
+ preparePiExtraSpawnConfig: async () => ({ mcpEnv: { HOME: root, USERPROFILE: root, XDG_CONFIG_HOME: path.join(root, 'xdg') } }),
+ };
+ const workingDir = path.join(root, 'work'); mkdirSync(workingDir);
+ const opts = { workingDir, model: 'fixture-alias', providerId: 'strict', permissionMode: 'bypassPermissions' as const };
+ const run = async (options: Parameters<AgentSessionHandle['send']>[1]) => {
+ const events: AgentEvent[] = [];
+ const finish = (async () => { for await (const event of handle!.events()) { events.push(event); if (event.type === 'done') break; } })();
+ await handle!.send({ type: 'user', content: 'Reply OK' }, options);
+ await finish;
+ return events;
+ };
+ const agent = new PiAgent(deps);
+ handle = await agent.startSession({ ...opts, sessionId: 'first' });
+ let userEntry = '';
+ const failed = await run({ onTranscriptUserEntry: async (id) => { userEntry = id; } });
+ const error = failed.find((event) => event.type === 'error')?.data as { reason: string; piCacheCompatibility: PiCacheCompatibility; piCacheRecoverySafe: boolean };
+ expect(error).toMatchObject({ reason: 'unsupported-request-option', piCacheRecoverySafe: true, piCacheCompatibility: { applied: false, providerId: 'strict', modelId: 'fixture-alias', wireModelId: 'fixture' } });
+ expect(userEntry).not.toBe('');
+ expect(received).toHaveLength(1);
+ learned = error.piCacheCompatibility;
+ const resumeSessionId = handle.id;
+ await handle.close();
+ handle = await agent.startSession({ ...opts, sessionId: 'rebuilt', resumeSessionId });
+ await expect(handle.send({ type: 'user', content: 'Reply OK' }, { [PI_CACHE_RECOVERY_EXPECTATION]: { ...learned, routeKey: '0'.repeat(64) }, retryTranscriptUserEntryId: userEntry })).rejects.toThrow(/not applied to the expected route/);
+ expect(received).toHaveLength(1);
+ const succeeded = await run({ [PI_CACHE_RECOVERY_EXPECTATION]: learned, retryTranscriptUserEntryId: userEntry });
+ expect(succeeded.some((event) => event.type === 'error')).toBe(false);
+ expect(succeeded.find((event) => event.type === 'done')?.data).toMatchObject({ result: 'OK' });
+ expect(received).toHaveLength(2);
+ expect(received[1]).not.toHaveProperty('prompt_cache_key');
+ expect(received[1]).not.toHaveProperty('prompt_cache_retention');
+ expect((received[1].messages as Array<{ role: string }>).filter((m) => m.role === 'user')).toHaveLength(1);
+ await handle.close();
+ handle = await agent.startSession({ ...opts, sessionId: 'new-task' });
+ expect((await run({})).some((event) => event.type === 'error')).toBe(false);
+ expect(received).toHaveLength(3);
+ expect(received[2]).not.toHaveProperty('prompt_cache_key');
+ await handle.close();
+ // A different endpoint under the same connection retains native caching.
+ endpoint += '/different';
+ rejectCacheFields = false;
+ handle = await agent.startSession({ ...opts, sessionId: 'working-gateway' });
+ expect((await run({})).some((event) => event.type === 'error')).toBe(false);
+ expect(received).toHaveLength(4);
+ expect(received[3]).toHaveProperty('prompt_cache_key');
+ expect(received[3]).toHaveProperty('prompt_cache_retention', '24h');
+ } finally {
+ await handle?.close();
+ gateway.closeAllConnections();
+ await new Promise<void>((resolve) => gateway.close(() => resolve()));
+ rmSync(root, { recursive: true, force: true });
+ }
+ }, 60_000);
+});
diff --git a/packages/maker-core/src/agents/pi/__tests__/cache-compatibility.test.ts b/packages/maker-core/src/agents/pi/__tests__/cache-compatibility.test.ts
new file mode 100644
index 0000000000..42d8dcb4a3
--- /dev/null
+++ b/packages/maker-core/src/agents/pi/__tests__/cache-compatibility.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { piCacheRouteKey } from '../cache-compatibility.js';
+describe('cache route identities', () => {
+ it('separates protocol, effective path, port and query routing', () => {
+ const a = piCacheRouteKey('https://example.test/v1?route=a', 'openai-completions');
+ expect(a).toMatch(/^[a-f0-9]{64}$/);
+ for (const url of ['https://example.test/v2?route=a', 'https://example.test:444/v1?route=a', 'https://example.test/v1?route=b']) {
+ expect(piCacheRouteKey(url, 'openai-completions')).not.toBe(a);
+ }
+ expect(piCacheRouteKey('https://example.test/v1?route=a', 'openai-responses')).not.toBe(a);
+ expect(piCacheRouteKey('https://example.test/v1?route=a#fragment', 'openai-completions')).toBe(a);
+ expect(piCacheRouteKey('not a URL', 'openai-completions')).toBeUndefined();
+ });
+});
diff --git a/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts b/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts
index 8d433b1655..8ee3ebdb55 100644
--- a/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts
+++ b/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts
@@ -2495,3 +2495,21 @@ it('lets cindy_mcp_call_tool omit args and forwards an empty object for no-param
arguments: { name: 'memory_list', args: {} },
});
});
+
+it('removes cache fields only for an exact learned Chat Completions route and preserves Fast', () => {
+ const start = CINDY_BRIDGE_EXTENSION_SOURCE.indexOf(' function learnedCachePayload(');
+ const end = CINDY_BRIDGE_EXTENSION_SOURCE.indexOf(" pi.on('before_provider_request'", start);
+ const model = { provider: 'connection-a', id: 'wire', baseUrl: 'http://localhost/api.openai.com/v1', api: 'openai-completions' };
+ let rules = JSON.stringify([model]);
+ const adapt = new Function('path', 'process', 'statSync', 'readFileSync', CINDY_BRIDGE_EXTENSION_SOURCE.slice(start, end) + '; return learnedCachePayload;')(
+ { join: (...v: string[]) => v.join('/') }, { env: { PI_CODING_AGENT_DIR: '/isolated' } }, () => ({ size: rules.length }), () => rules,
+ );
+ const original = { messages: [], prompt_cache_key: 'key', prompt_cache_retention: '24h', service_tier: 'priority' };
+ expect(adapt(original, model)).toEqual({ messages: [], service_tier: 'priority' });
+ expect(original.prompt_cache_key).toBe('key');
+ expect(adapt(original, { ...model, provider: 'connection-b' })).toBe(original);
+ expect(adapt(original, { ...model, baseUrl: 'http://other/v1' })).toBe(original);
+ expect(adapt(original, { ...model, api: 'openai-responses' })).toBe(original);
+ rules = '{bad-json';
+ expect(adapt(original, model)).toBe(original);
+});
diff --git a/packages/maker-core/src/agents/pi/__tests__/cindySubagentForeground.test.ts b/packages/maker-core/src/agents/pi/__tests__/cindySubagentForeground.test.ts
index 22bcf36f9f..486a5249f7 100644
--- a/packages/maker-core/src/agents/pi/__tests__/cindySubagentForeground.test.ts
+++ b/packages/maker-core/src/agents/pi/__tests__/cindySubagentForeground.test.ts
@@ -154,6 +154,8 @@ describe('Cindy PI Subagent foreground durable path', () => {
'waits for the runner and forwards Ask approval through the parent UI',
async () => {
const f = await fixture();
+ const cacheRules = [{ provider: 'fixture', id: 'fixture-model', baseUrl: 'https://fixture.invalid/v1' }];
+ await writeFile(path.join(f.configHome, 'pi-cache-compatibility.json'), JSON.stringify(cacheRules));
const previous = { ...process.env };
Object.assign(process.env, {
[CINDY_SUBAGENT_ENV.binary]: process.execPath,
@@ -208,6 +210,7 @@ describe('Cindy PI Subagent foreground durable path', () => {
`foreground approved result:${expectedRouteToken}`,
);
const [runId] = await readdir(f.runRoot);
+ expect(JSON.parse(await readFile(path.join(f.runRoot, runId, 'pi-home', 'pi-cache-compatibility.json'), 'utf8'))).toEqual(cacheRules);
const configText = await readFile(path.join(f.runRoot, runId, 'config.json'), 'utf8');
const config = JSON.parse(configText);
expect(config.tasks[0]).toMatchObject({
diff --git a/packages/maker-core/src/agents/pi/__tests__/pi-provider-routing.test.ts b/packages/maker-core/src/agents/pi/__tests__/pi-provider-routing.test.ts
index 80a76c6377..9f29e77fdc 100644
--- a/packages/maker-core/src/agents/pi/__tests__/pi-provider-routing.test.ts
+++ b/packages/maker-core/src/agents/pi/__tests__/pi-provider-routing.test.ts
@@ -18,6 +18,7 @@ vi.setConfig({ testTimeout: 30_000 });
import { CINDY_BRIDGE_EXTENSION_SOURCE } from "../cindy-bridge-source.js";
import { CINDY_SUBAGENT_EXTENSION_SOURCE } from "../cindy-subagent-source.js";
+import { piCacheRouteKey } from '../cache-compatibility.js';
const captured = vi.hoisted(() => ({
args: [] as string[],
@@ -1259,6 +1260,132 @@ describe("Pi provider-aware model routing", () => {
await handle.close();
});
+ it.each([false, true])("scopes learned compatibility to the real upstream behind a proxy: %s", async (proxied) => {
+ const agent = new PiAgent({
+ auth: {
+ getState: async () => ({
+ authenticated: true,
+ identity: "custom",
+ authSource: "api-key" as const,
+ }),
+ triggerLogin: async () => ({ authenticated: true }),
+ logout: async () => {},
+ getAuthEnv: async () => ({}),
+ },
+ runtimeConfig: { endpoint: "http://127.0.0.1:9988" },
+ binaryPath: path.join(agentHome, "pi"),
+ logger: noopLogger,
+ capabilityAdditions: {
+ availableModels: [
+ {
+ id: "glm-5.3-flash",
+ displayName: "GLM-5.3-Flash",
+ contextWindow: 1_000_000,
+ efforts: ["low", "high", "max"],
+ defaultEffort: "high",
+ },
+ ],
+ },
+ resolvePiAgentHome: () => agentHome,
+ resolvePiNativeCompatOverride: (providerId, modelId, routeKey) =>
+ (modelId === "glm-5.3-flash" || modelId === "glm-5.3-wire") &&
+ providerId === "opencode-go" && routeKey === piCacheRouteKey('https://opencode.ai/zen/go/v1', 'openai-completions')
+ ? { supportsLongCacheRetention: false }
+ : undefined,
+ resolvePiNativeProviders: async () => ({
+ providers: [
+ {
+ id: "opencode-go",
+ sourceProviderId: "opencode-go",
+ name: "OpenCode Go",
+ baseUrl: proxied ? 'http://127.0.0.1:19988/v1' : "https://opencode.ai/zen/go/v1",
+ ...(proxied ? { cacheIdentityBaseUrl: 'https://opencode.ai/zen/go/v1' } : {}),
+ api: "openai-completions",
+ models: [
+ {
+ id: "glm-5.3-flash",
+ api: "openai-completions",
+ reasoning: true,
+ contextWindow: 1_000_000,
+ maxTokens: 131_072,
+ compat: {
+ supportsStore: false,
+ supportsDeveloperRole: false,
+ maxTokensField: "max_tokens",
+ },
+ },
+ {
+ // Public model ID differs from wire ID; only the wire identity is learned.
+ id: "glm-5.3",
+ wireId: "glm-5.3-wire",
+ api: "openai-completions",
+ reasoning: true,
+ contextWindow: 1_000_000,
+ maxTokens: 131_072,
+ },
+ ],
+ },
+ {
+ // BYOM:models.json 键是命名空间化 runtime id,会话/自愈键是 sourceProviderId。
+ id: "cindy-byom-opencode-go",
+ sourceProviderId: "opencode-go",
+ name: "OpenCode Go (BYOM)",
+ baseUrl: "https://opencode.ai/zen/go/v1",
+ api: "openai-completions",
+ models: [
+ {
+ id: "glm-5.3-flash",
+ api: "openai-completions",
+ reasoning: true,
+ contextWindow: 1_000_000,
+ maxTokens: 131_072,
+ },
+ ],
+ },
+ ],
+ env: {},
+ }),
+ });
+ const handle = await agent.startSession({
+ sessionId: "pi-native-compat-override",
+ workingDir: cwd,
+ model: "glm-5.3-flash",
+ providerId: "opencode-go",
+ });
+ const models = JSON.parse(
+ readFileSync(
+ path.join(captured.env.PI_CODING_AGENT_DIR as string, "models.json"),
+ "utf8",
+ ),
+ ) as { providers: Record<string, { models?: Array<Record<string, unknown>> }> };
+ expect(models.providers["opencode-go"]?.models).toEqual([
+ expect.objectContaining({
+ id: "glm-5.3-flash",
+ compat: expect.objectContaining({
+ supportsStore: false,
+ supportsDeveloperRole: false,
+ maxTokensField: "max_tokens",
+ supportsLongCacheRetention: false,
+ }),
+ }),
+ // The learned wire model is distinct from the public model alias.
+ expect.objectContaining({
+ id: "glm-5.3-wire",
+ compat: { supportsLongCacheRetention: false },
+ }),
+ ]);
+ // BYOM 命名空间 provider 用 sourceProviderId 命中同一条学习结果。
+ expect(models.providers["cindy-byom-opencode-go"]?.models).toEqual([
+ expect.objectContaining({
+ id: "glm-5.3-flash",
+ compat: { supportsLongCacheRetention: false },
+ }),
+ ]);
+ const rules = JSON.parse(readFileSync(path.join(captured.env.PI_CODING_AGENT_DIR as string, 'pi-cache-compatibility.json'), 'utf8'));
+ expect(rules).toContainEqual({ provider: 'opencode-go', id: 'glm-5.3-wire', baseUrl: proxied ? 'http://127.0.0.1:19988/v1' : 'https://opencode.ai/zen/go/v1' });
+ await handle.close();
+ });
+
it("routes a persisted BYOM id through its namespaced PI runtime provider", async () => {
const authProviderIds: Array<string | null | undefined> = [];
const deps: AgentDeps = {
@@ -3231,7 +3358,13 @@ describe("Pi provider-aware model routing", () => {
logout: async () => {},
getAuthEnv: async () => ({ CINDY_PI_API_KEY: "gateway-key" }),
},
- runtimeConfig: { endpoint: "http://127.0.0.1:9988/" },
+ runtimeConfig: {
+ endpoint: "http://127.0.0.1:9988/",
+ get remoteEndpoint() {
+ if (api !== 'openai-completions') throw new Error('Unrelated protocol must not read cache identity');
+ return 'https://gateway.example.test/v1';
+ },
+ },
binaryPath: path.join(agentHome, "pi"),
logger: noopLogger,
capabilityAdditions: {
@@ -3327,7 +3460,7 @@ describe("Pi provider-aware model routing", () => {
logout: async () => {},
getAuthEnv: async () => ({ CINDY_PI_API_KEY: 'gateway-key' }),
},
- runtimeConfig: { endpoint: 'http://127.0.0.1:9988/' },
+ runtimeConfig: { endpoint: 'http://127.0.0.1:9988/', remoteEndpoint: 'https://gateway.test/v1' },
binaryPath: path.join(agentHome, 'pi'),
logger: noopLogger,
capabilityAdditions: {
@@ -3387,7 +3520,7 @@ describe("Pi provider-aware model routing", () => {
logout: async () => {},
getAuthEnv: async () => ({ CINDY_PI_API_KEY: 'gateway-key' }),
},
- runtimeConfig: { endpoint: 'http://127.0.0.1:9988/' },
+ runtimeConfig: { endpoint: 'http://127.0.0.1:9988/', remoteEndpoint: 'https://gateway.test/v1' },
binaryPath: path.join(agentHome, 'pi'),
logger: noopLogger,
capabilityAdditions: {
@@ -3431,6 +3564,61 @@ describe("Pi provider-aware model routing", () => {
await handle.close();
});
+ it('merges a learned compat override into the gateway models.json block', async () => {
+ const deps: AgentDeps = {
+ auth: {
+ getState: async () => ({ authenticated: true, identity: 'test', authSource: 'api-key' as const }),
+ triggerLogin: async () => ({ authenticated: true }),
+ logout: async () => {},
+ getAuthEnv: async () => ({ CINDY_PI_API_KEY: 'gateway-key' }),
+ },
+ runtimeConfig: { endpoint: 'http://127.0.0.1:9988/', remoteEndpoint: 'https://gateway.test/v1' },
+ binaryPath: path.join(agentHome, 'pi'),
+ logger: noopLogger,
+ capabilityAdditions: {
+ availableModels: [{
+ id: 'z-ai/glm-5.3-flash',
+ displayName: 'GLM 5.3 Flash',
+ contextWindow: 200_000,
+ efforts: ['low', 'high'],
+ defaultEffort: 'high',
+ }],
+ },
+ resolvePiAgentHome: () => agentHome,
+ resolvePiGatewayModelSpec: () => ({
+ api: 'openai-completions',
+ compat: { supportsStore: false },
+ }),
+ resolvePiNativeCompatOverride: (providerId, modelId, routeKey) =>
+ providerId === 'xd' && modelId === 'z-ai/glm-5.3-flash' && routeKey === piCacheRouteKey('https://gateway.test/v1', 'openai-completions')
+ ? { supportsLongCacheRetention: false }
+ : undefined,
+ };
+ const handle = await new PiAgent(deps).startSession({
+ sessionId: 'gateway-compat-override',
+ workingDir: cwd,
+ model: 'z-ai/glm-5.3-flash',
+ providerId: 'xd',
+ effort: 'high',
+ });
+ const models = JSON.parse(
+ readFileSync(path.join(captured.env.PI_CODING_AGENT_DIR as string, 'models.json'), 'utf8'),
+ ) as {
+ providers: Record<string, { models?: Array<{ id: string; compat?: Record<string, unknown> }> }>;
+ };
+ // gateway 路由也必须吃上自愈结果,否则学习一次却不生效、还被防循环闩锁永久关闭。
+ expect(models.providers.cindy?.models).toEqual([
+ expect.objectContaining({
+ id: 'z-ai/glm-5.3-flash',
+ compat: expect.objectContaining({
+ supportsStore: false,
+ supportsLongCacheRetention: false,
+ }),
+ }),
+ ]);
+ await handle.close();
+ });
+
it('keeps BYOM startup when the model is outside the XD v3 Pi catalog', async () => {
const deps: AgentDeps = {
auth: {
@@ -4290,11 +4478,13 @@ describe("Pi provider-aware model routing", () => {
it('restores exact private catalog bytes when the adapter rejects before mutation', async () => {
let name = 'Before';
+ let learned = false;
const deps = byomDeps(async () => ({ providers: [{
id: 'native-a', name: 'Native A', adapterProvider: 'openai',
baseUrl: 'http://a.test', api: 'openai-completions',
models: [{ id: 'local-model', name, contextWindow: 200_000 }],
}], env: {} }));
+ deps.resolvePiNativeCompatOverride = () => learned ? { supportsLongCacheRetention: false } : undefined;
const handle = await new PiAgent(deps).startSession({
sessionId: 'invalid-refresh-rollback', workingDir: cwd,
model: 'local-model', providerId: 'native-a',
@@ -4304,13 +4494,17 @@ describe("Pi provider-aware model routing", () => {
const settingsPath = path.join(configHome, 'settings.json');
const beforeModels = readFileSync(modelsPath, 'utf8');
const beforeSettings = readFileSync(settingsPath, 'utf8');
+ const rulesPath = path.join(configHome, 'pi-cache-compatibility.json');
+ const beforeRules = readFileSync(rulesPath, 'utf8');
name = 'After';
+ learned = true;
captured.refreshAckMode = 'invalid';
captured.requests.length = 0;
await expect(handle.setModel!('local-model', { providerId: 'native-a' }))
.rejects.toThrow(/rejected the native provider refresh payload/);
expect(readFileSync(modelsPath, 'utf8')).toBe(beforeModels);
expect(readFileSync(settingsPath, 'utf8')).toBe(beforeSettings);
+ expect(readFileSync(rulesPath, 'utf8')).toBe(beforeRules);
expect(captured.requests.some((request) => request.type === 'set_model')).toBe(false);
expect(captured.closes).toBe(0);
await handle.close();
diff --git a/packages/maker-core/src/agents/pi/__tests__/pi-translator.test.ts b/packages/maker-core/src/agents/pi/__tests__/pi-translator.test.ts
index 68d8ed0cd0..d009760739 100644
--- a/packages/maker-core/src/agents/pi/__tests__/pi-translator.test.ts
+++ b/packages/maker-core/src/agents/pi/__tests__/pi-translator.test.ts
@@ -487,6 +487,73 @@ describe('pi translator', () => {
}));
});
+ it('classifies a prompt_cache_retention rejection for provider compat self-heal', () => {
+ const ctx = createPiTranslateContext(noopLogger);
+ const { queue, events } = makeQueue();
+ translatePiEvent(ev({ type: 'agent_start' }), queue, ctx);
+ translatePiEvent(
+ ev({
+ type: 'message_end',
+ message: {
+ role: 'assistant',
+ content: [],
+ stopReason: 'error',
+ errorMessage:
+ '400: {"param":"prompt_cache_retention","type":"invalid_request_error","message":'
+ + '"prompt_cache_retention is not supported by this endpoint; use prompt_cache_options"}',
+ usage: { input: 0, output: 0 },
+ },
+ }),
+ queue,
+ ctx,
+ );
+ translatePiEvent(ev({ type: 'agent_settled' }), queue, ctx);
+
+ expect(events.filter((event) => event.type === 'error')).toEqual([
+ expect.objectContaining({
+ source: 'pi',
+ data: expect.objectContaining({
+ isTerminal: true,
+ reason: 'unsupported-request-option',
+ }),
+ }),
+ ]);
+ });
+
+
+ it('classifies a custom gateway prompt_cache_key rejection for provider compat self-heal', () => {
+ const ctx = createPiTranslateContext(noopLogger);
+ const { queue, events } = makeQueue();
+ translatePiEvent(ev({ type: 'agent_start' }), queue, ctx);
+ translatePiEvent(
+ ev({
+ type: 'message_end',
+ message: {
+ role: 'assistant',
+ content: [],
+ stopReason: 'error',
+ errorMessage:
+ '400: {"message":"Validation: Unsupported parameter(s): `prompt_cache_key`",'
+ + '"type":"invalid_request_error"}',
+ usage: { input: 0, output: 0 },
+ },
+ }),
+ queue,
+ ctx,
+ );
+ translatePiEvent(ev({ type: 'agent_settled' }), queue, ctx);
+
+ expect(events.filter((event) => event.type === 'error')).toEqual([
+ expect.objectContaining({
+ source: 'pi',
+ data: expect.objectContaining({
+ isTerminal: true,
+ reason: 'unsupported-request-option',
+ }),
+ }),
+ ]);
+ });
+
it.each(['DeepSeek-V4-Flash-0731', 'claude-sonnet-4-6'])('preserves length-limited text and usage for %s', (model) => {
const ctx = createPiTranslateContext(noopLogger);
const { queue, events } = makeQueue();
@@ -2354,3 +2421,19 @@ describe('pi translator live token speed', () => {
}
});
});
+
+it.each(['none', 'thinking', 'tool'])('reports a route receipt and blocks recovery after %s output', (kind) => {
+ const ctx = createPiTranslateContext(noopLogger);
+ const { queue, events } = makeQueue();
+ const receipt = { providerId: 'connection-a', modelId: 'public', wireModelId: 'wire', routeKey: 'a'.repeat(64), applied: false };
+ ctx.getCacheCompatibility = () => receipt;
+ translatePiEvent(ev({ type: 'agent_start' }), queue, ctx);
+ if (kind === 'thinking') translatePiEvent(ev({ type: 'message_update', assistantMessageEvent: { type: 'thinking_delta', delta: 'working' } }), queue, ctx);
+ if (kind === 'tool') translatePiEvent(ev({ type: 'tool_execution_start', toolCallId: 'one', toolName: 'bash', args: { command: 'true' } }), queue, ctx);
+ translatePiEvent(ev({ type: 'message_end', message: { role: 'assistant', content: [], stopReason: 'error', errorMessage: '400: {"message":"Unsupported parameter(s): prompt_cache_key"}' } }), queue, ctx);
+ translatePiEvent(ev({ type: 'agent_settled' }), queue, ctx);
+ expect(events.find((event) => event.type === 'error')?.data).toMatchObject({
+ reason: 'unsupported-request-option', piCacheCompatibility: receipt, piCacheRecoverySafe: kind === 'none',
+ });
+ disposePiTranslateContext(ctx);
+});
diff --git a/packages/maker-core/src/agents/pi/cache-compatibility.ts b/packages/maker-core/src/agents/pi/cache-compatibility.ts
new file mode 100644
index 0000000000..7276531a0b
--- /dev/null
+++ b/packages/maker-core/src/agents/pi/cache-compatibility.ts
@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+
+/** Host-owned routing receipt; contains no URL, credential or request content. */
+export interface PiCacheCompatibility {
+ providerId: string;
+ modelId: string;
+ wireModelId: string;
+ routeKey: string;
+ applied: boolean;
+}
+
+/** Include paths and query routing in the digest. Never persist the source URL. */
+export function piCacheRouteKey(endpoint: string, api: string): string | undefined {
+ try {
+ const url = new URL(endpoint);
+ if (!['http:', 'https:'].includes(url.protocol) || !url.hostname) return undefined;
+ url.hash = '';
+ return createHash('sha256').update(JSON.stringify(['pi-cache-v1', api, url.href])).digest('hex');
+ } catch {
+ return undefined;
+ }
+}
diff --git a/packages/maker-core/src/agents/pi/cindy-bridge-source.ts b/packages/maker-core/src/agents/pi/cindy-bridge-source.ts
index 5e3e92159c..056a0703dc 100644
--- a/packages/maker-core/src/agents/pi/cindy-bridge-source.ts
+++ b/packages/maker-core/src/agents/pi/cindy-bridge-source.ts
@@ -3957,9 +3957,22 @@ export default async function cindyBridge(piApi: any) {
},
});
if (!currentPermissionState().reviewOnly) registerCindyQuestionTool(pi);
+ function learnedCachePayload(payload, model) {
+ if (model?.api !== 'openai-completions' || !payload || typeof payload !== 'object' || Array.isArray(payload)) return payload;
+ try {
+ const file = path.join(process.env.PI_CODING_AGENT_DIR || '', 'pi-cache-compatibility.json');
+ if (!process.env.PI_CODING_AGENT_DIR || statSync(file).size > 256 * 1024) return payload;
+ const rules = JSON.parse(readFileSync(file, 'utf8'));
+ if (!Array.isArray(rules) || !rules.some((rule) => rule.provider === model.provider && rule.id === model.id && rule.baseUrl === model.baseUrl)) return payload;
+ const next = { ...payload };
+ delete next.prompt_cache_key;
+ delete next.prompt_cache_retention;
+ return next;
+ } catch { return payload; }
+ }
pi.on('before_provider_request', async (event, ctx) => {
const payload = astraResponsesPayload(event.payload, ctx.model) ?? event.payload;
- return (await nativeFastPayload(payload, ctx.model, ctx)) ?? payload;
+ return learnedCachePayload((await nativeFastPayload(payload, ctx.model, ctx)) ?? payload, ctx.model);
});
const mcpGateway = new CindyMcpGateway();
// bash 隔离 home 经 resolveBashPackageHome 解析(首次加载读删 + 防篡改 stash,
diff --git a/packages/maker-core/src/agents/pi/cindy-subagent-source.ts b/packages/maker-core/src/agents/pi/cindy-subagent-source.ts
index e3c5e643a1..6fabf8bab4 100644
--- a/packages/maker-core/src/agents/pi/cindy-subagent-source.ts
+++ b/packages/maker-core/src/agents/pi/cindy-subagent-source.ts
@@ -1036,6 +1036,14 @@ async function launchDurableRun(binary, tasks, runtime, taskId, mode, context, d
try { chmodSync(permissionFile, 0o600); } catch (err) { /* best effort on Windows */ }
mkdirSync(childConfigHome, { recursive: true, mode: 0o700 });
copyFileSync(join(configHome, 'models.json'), join(childConfigHome, 'models.json'));
+ // Freeze the same learned rules as models.json for durable children.
+ const childCacheRules = join(childConfigHome, 'pi-cache-compatibility.json');
+ try {
+ copyFileSync(join(configHome, 'pi-cache-compatibility.json'), childCacheRules);
+ chmodSync(childCacheRules, 0o600);
+ } catch (error) {
+ if (!error || error.code !== 'ENOENT') throw error;
+ }
// Parent configHome is ephemeral. Durable children outlive it, so Pi native
// grep (PI_CODING_AGENT_DIR/bin) and the Cindy find override need a private copy.
copyManagedRipgrep(configHome, childConfigHome);
diff --git a/packages/maker-core/src/agents/pi/index.ts b/packages/maker-core/src/agents/pi/index.ts
index 9e5671f11f..1505a9b396 100644
--- a/packages/maker-core/src/agents/pi/index.ts
+++ b/packages/maker-core/src/agents/pi/index.ts
@@ -25,6 +25,7 @@ import { canonicalSkillPath, snapshotDisabledSkillLaunch, currentDisabledSkillLa
*/
import { LIBRARY_READ_ROOT, libraryNativeReadContext } from '../shared/library-native-read.js';
+import { piCacheRouteKey, type PiCacheCompatibility } from './cache-compatibility.js';
import os from 'node:os';
import path from 'node:path';
import { constants as fsConstants, promises as fs } from 'node:fs';
@@ -69,6 +70,7 @@ import {
ASYNC_QUESTION_ANSWER,
PINNED_SKILL_INVOCATION,
PI_REQUEST_BODY_RECOVERY_EXHAUSTED,
+ PI_CACHE_RECOVERY_EXPECTATION,
PiManagedPackageMutationCancelledError,
PiManagedPackageMutationFailedError,
projectPiPackageCommandDiagnostic,
@@ -2249,6 +2251,7 @@ export class PiAgent extends BaseAgent {
omitGatewayModels?: boolean;
} = {},
): Promise<{
+ cacheRoutes: Map<string, PiCacheCompatibility>;
gatewayImageInputByModel: Map<string, boolean>;
gatewayApiByModel: Map<string, PiGatewayApi>;
/** models.json + settings.json 内容 sha256 —— 远端 daemon 启动身份的一部分。 */
@@ -2283,6 +2286,24 @@ export class PiAgent extends BaseAgent {
: publicModels;
const gatewayImageInputByModel = new Map<string, boolean>();
const gatewayApiByModel = new Map<string, PiGatewayApi>();
+ const cacheRoutes = new Map<string, PiCacheCompatibility>();
+ const cacheRequestRules: Array<{ provider: string; id: string; baseUrl: string }> = [];
+ const learnedCompat = (providerId: string, modelId: string, wireModelId: string,
+ runtimeProvider: string, baseUrl: string, api: string, runtimeBaseUrl = baseUrl) => {
+ // Unknown identities and SSH must not consume local learning records.
+ if (opts.remote || api !== 'openai-completions') return undefined;
+ const routeKey = piCacheRouteKey(baseUrl, api);
+ if (!routeKey) return undefined;
+ const compat = this.deps.resolvePiNativeCompatOverride?.(providerId, wireModelId, routeKey);
+ cacheRoutes.set(JSON.stringify([runtimeProvider, wireModelId]), {
+ providerId, modelId, wireModelId, routeKey,
+ applied: compat?.supportsLongCacheRetention === false,
+ });
+ if (compat?.supportsLongCacheRetention === false && !cacheRequestRules.some((rule) => rule.provider === runtimeProvider && rule.id === wireModelId)) {
+ cacheRequestRules.push({ provider: runtimeProvider, id: wireModelId, baseUrl: runtimeBaseUrl });
+ }
+ return compat;
+ };
const models = runtimeModels.flatMap((publicModel: ModelDescriptor) => {
// availableModels 为跨 provider 拍平的公开能力;BYOM 同 id 冲突时 effort
// 会按设计收敛成交集。cindy gateway 块则代表内置路由,必须回查其
@@ -2325,6 +2346,12 @@ export class PiAgent extends BaseAgent {
return [];
}
const modelBaseUrl = endpoint ? piGatewayModelBaseUrl(endpoint, api) : undefined;
+ const gatewayCompat = {
+ ...(resolvedSpec?.compat ?? {}),
+ ...(!opts.remote && api === 'openai-completions' ?
+ learnedCompat(gatewayProviderId ?? 'xd', m.id, m.id, PI_PROVIDER_ID,
+ this.deps.runtimeConfig.remoteEndpoint ?? '', api, modelBaseUrl ?? '') ?? {} : {}),
+ };
gatewayApiByModel.set(m.id, api);
// Missing capability metadata must not disable newly discovered vision models.
// Explicit text-only declarations still take precedence over this default.
@@ -2347,7 +2374,7 @@ export class PiAgent extends BaseAgent {
}
: {}),
...(thinkingLevelMap ? { thinkingLevelMap } : {}),
- ...(resolvedSpec?.compat ? { compat: structuredClone(resolvedSpec.compat) } : {}),
+ ...(Object.keys(gatewayCompat).length > 0 ? { compat: structuredClone(gatewayCompat) } : {}),
...(resolvedSpec?.samplingParams
? { samplingParams: structuredClone(resolvedSpec.samplingParams) }
: {}),
@@ -2392,6 +2419,10 @@ export class PiAgent extends BaseAgent {
this.deps.logger.warn('pi: native provider id collides with gateway provider "cindy" — skipped', { id: np.id });
continue;
}
+ // Inherited bundled models need the same learning in modelOverrides.
+ for (const model of np.models) learnedCompat(np.sourceProviderId ?? np.id, model.id,
+ model.wireId ?? model.id, np.id, model.cacheIdentityBaseUrl ?? np.cacheIdentityBaseUrl ?? model.baseUrl ?? np.baseUrl,
+ model.api ?? np.api ?? '', model.baseUrl ?? np.baseUrl);
const nativeModels = (
np.inheritModels ? np.models.filter((model) => model.api !== undefined || model.catalogAddition === true) : np.models
).map((m) => {
@@ -2399,8 +2430,18 @@ export class PiAgent extends BaseAgent {
m.contextWindow && m.contextWindow > 0 ? m.contextWindow : 128_000,
this.deps.resolveModelContextLimit?.(np.sourceProviderId ?? np.id, m.id) ?? 0,
);
+ // 自愈写回的 per-model compat 覆盖(如上游拒收长缓存提示后关掉
+ // supportsLongCacheRetention)与目录/bundled compat 合并;覆盖字段最少,
+ // 不改路由与凭证。
+ const wireModelId = m.wireId ?? m.id;
+ const compat = {
+ ...(m.compat ?? {}),
+ ...(learnedCompat(np.sourceProviderId ?? np.id, m.id, wireModelId, np.id,
+ m.cacheIdentityBaseUrl ?? np.cacheIdentityBaseUrl ?? m.baseUrl ?? np.baseUrl,
+ m.api ?? np.api ?? '', m.baseUrl ?? np.baseUrl) ?? {}),
+ };
return {
- id: m.wireId ?? m.id,
+ id: wireModelId,
name: m.name ?? m.id,
...(m.baseUrl ? { baseUrl: m.baseUrl } : {}),
...(m.headers && Object.keys(m.headers).length > 0 ? { headers: m.headers } : {}),
@@ -2411,7 +2452,7 @@ export class PiAgent extends BaseAgent {
contextWindow,
maxTokens: m.maxTokens && m.maxTokens > 0 ? m.maxTokens : piMaxTokensFallback(contextWindow),
...(m.cost ? { cost: structuredClone(m.cost) } : {}),
- ...(m.compat ? { compat: structuredClone(m.compat) } : {}),
+ ...(Object.keys(compat).length > 0 ? { compat: structuredClone(compat) } : {}),
...(m.samplingParams ? { samplingParams: structuredClone(m.samplingParams) } : {}),
};
});
@@ -2430,8 +2471,12 @@ export class PiAgent extends BaseAgent {
modelOverrides: Object.fromEntries(np.models.flatMap((model) => {
const window = Math.max(model.contextWindow ?? 0,
this.deps.resolveModelContextLimit?.(np.sourceProviderId ?? np.id, model.id) ?? 0);
- return typeof window === 'number' && Number.isSafeInteger(window) && window > 0
- ? [[model.wireId ?? model.id, { contextWindow: window }]] : [];
+ const contextWindow = Number.isSafeInteger(window) && window > 0 ? window : undefined;
+ const compat = cacheRoutes.get(JSON.stringify([np.id, model.wireId ?? model.id]))?.applied
+ ? { ...(model.compat ?? {}), supportsLongCacheRetention: false } : undefined;
+ return contextWindow || compat ? [[model.wireId ?? model.id, {
+ ...(contextWindow ? { contextWindow } : {}), ...(compat ? { compat } : {}),
+ }]] : [];
})),
} : {}),
...(np.headers && Object.keys(np.headers).length > 0 ? { headers: np.headers } : {}),
@@ -2513,12 +2558,16 @@ export class PiAgent extends BaseAgent {
// 控制面文件:显式 600,防同机其他用户读 BYOM baseUrl / provider 路由
// (R5 安全审计 H-5)。
await fs.writeFile(modelsJsonPath, modelsJsonContent, { mode: 0o600 });
+ await fs.writeFile(path.join(agentHome, 'pi-cache-compatibility.json'), JSON.stringify(
+ cacheRequestRules,
+ ), { mode: 0o600 });
await fs.writeFile(settingsJsonPath, settingsJsonContent, {
mode: 0o600,
});
}
}
return {
+ cacheRoutes,
gatewayImageInputByModel,
gatewayApiByModel,
// 远端 daemon 启动身份:models.json + settings.json。BYOM/gateway 或 retry
@@ -3227,7 +3276,7 @@ export class PiAgent extends BaseAgent {
`${stableSessionPathSegment(opts.sessionId)}-${preview.modelsJsonHash.slice(0, 16)}${globalContextHash ? `-${globalContextHash}` : ''}`,
);
}
- const { gatewayImageInputByModel, gatewayApiByModel, modelsJsonHash, modelConfigHash } = await this.writeModelsJson(
+ const { cacheRoutes, gatewayImageInputByModel, gatewayApiByModel, modelsJsonHash, modelConfigHash } = await this.writeModelsJson(
configHome,
nativeProviders,
retainedRuntimeModel,
@@ -4046,6 +4095,7 @@ export class PiAgent extends BaseAgent {
// follow-up send)同口径。清空只认 turn 终态,由 send 预检覆盖为最新值。
let activeTurnPermissionPolicy: TurnPermissionPolicy | null = null;
let mutableModel = opts.model;
+ let appliedCacheRoutes = cacheRoutes;
let appliedModelConfigHash = modelConfigHash;
let pendingCurrentDescriptorRefresh = false;
let retainedLiveGatewayModel = initialProvider === PI_PROVIDER_ID ? selectedRuntimeModel : undefined;
@@ -4061,6 +4111,10 @@ export class PiAgent extends BaseAgent {
// null/订阅来源会归一到 cindy,setModel 未显式传来源时也必须跟随本次解析结果。
let mutablePiProviderId = initialProvider;
let mutableProviderId: string | null | undefined = opts.providerId ?? authProviderId;
+ ctx.getCacheCompatibility = () => {
+ const route = appliedCacheRoutes.get(JSON.stringify([mutablePiProviderId, mutableWireModel]));
+ return route ? { ...route, modelId: mutableModel ?? route.modelId } : undefined;
+ };
let activeEffortSnapshot = initialEffortSnapshot;
let mutableEffort: Effort | null = startupEffort ?? null;
let currentAutoReviewIntent: AutoReviewUserIntent = '';
@@ -6714,6 +6768,8 @@ export class PiAgent extends BaseAgent {
const previousGatewayModel = retainedLiveGatewayModel;
const modelsPath = joinRemotePosixPath(configHome, 'models.json');
const settingsPath = joinRemotePosixPath(configHome, 'settings.json');
+ const cacheRulesPath = path.join(configHome, 'pi-cache-compatibility.json');
+ const oldCacheRules = fileOps ? undefined : await fs.readFile(cacheRulesPath, 'utf8');
// Capture exact private bytes. Rebuilding from a live catalog would not be
// a rollback if the catalog changed after the session started.
const [oldModelsContent, oldSettingsContent] = await Promise.all([
@@ -6737,6 +6793,7 @@ export class PiAgent extends BaseAgent {
} else {
await fs.writeFile(modelsPath, oldModelsContent, { mode: 0o600 });
await fs.writeFile(settingsPath, oldSettingsContent, { mode: 0o600 });
+ await fs.writeFile(cacheRulesPath, oldCacheRules!, { mode: 0o600 });
}
} catch (error) {
await terminateUnconfirmedCatalogReload(error);
@@ -6868,6 +6925,7 @@ export class PiAgent extends BaseAgent {
}
gatewayImageInputByModel.clear();
for (const [key, value] of written.gatewayImageInputByModel) gatewayImageInputByModel.set(key, value);
+ appliedCacheRoutes = written.cacheRoutes;
appliedModelConfigHash = written.modelConfigHash;
// A full registry refresh can update the still-active A while a proposed
// switch to B later fails. Keep A pending until a confirmed set_model.
@@ -7179,6 +7237,14 @@ export class PiAgent extends BaseAgent {
throw new TurnDispatchRejectedError('Pi RPC is unavailable before prompt dispatch');
}
if (sendOpts) handle.validateSendOptions?.(sendOpts);
+ const expectedCompat = sendOpts?.[PI_CACHE_RECOVERY_EXPECTATION];
+ if (expectedCompat) {
+ const applied = ctx.getCacheCompatibility?.();
+ if (!sendOpts?.retryTranscriptUserEntryId || !applied?.applied || applied.routeKey !== expectedCompat.routeKey
+ || applied.providerId !== expectedCompat.providerId || applied.wireModelId !== expectedCompat.wireModelId) {
+ throw new TurnDispatchRejectedError('Pi cache compatibility was not applied to the expected route');
+ }
+ }
// 本轮策略覆盖:无策略显式清 null,不继承上一轮渠道策略(§7.2.5);内部续跑
// (plan 审批实施轮 / 自动继续)不经 send,仍读这份闭包值继承(§7.10)。
// provider 接受前任何失败都必须撤销,避免"任务显示已开始、实际未启动"却残留策略。
@@ -7252,7 +7318,10 @@ export class PiAgent extends BaseAgent {
const before = await proc.request({ type: 'get_tree' });
if (!before.success) throw new TurnDispatchRejectedError('Pi retry history unavailable');
const branch = piRetryBranch(before.data, sendOpts.retryTranscriptUserEntryId!);
- if (!branch) return;
+ if (!branch) {
+ if (expectedCompat) throw new TurnDispatchRejectedError('Pi cache recovery branch is not replayable');
+ return;
+ }
rejectIfCancelled(sendOpts, 'send');
// Native navigation preserves the old failed branch in the append-only
// transcript. Only the active model context is replaced by this retry.
@@ -7507,6 +7576,9 @@ export class PiAgent extends BaseAgent {
rejectIfCancelled(sendOpts, 'steer');
rejectIfUnavailable();
if (sendOpts) handle.validateSendOptions?.(sendOpts);
+ if (sendOpts?.[PI_CACHE_RECOVERY_EXPECTATION]) {
+ throw new TurnDispatchRejectedError('Pi cache recovery cannot steer an active turn');
+ }
if (reviewMode) {
await assertReviewMessageContentPaths(message.content, opts.workingDir, reviewReadGrants);
}
diff --git a/packages/maker-core/src/agents/pi/translator.ts b/packages/maker-core/src/agents/pi/translator.ts
index 73eeef2dd8..b261b85b3d 100644
--- a/packages/maker-core/src/agents/pi/translator.ts
+++ b/packages/maker-core/src/agents/pi/translator.ts
@@ -47,6 +47,10 @@ import {
UPSTREAM_STREAM_INTERRUPTED_REASON,
isStreamInterruptedErrorMessage,
} from '../shared/stream-interrupt-error.js';
+import {
+ UNSUPPORTED_REQUEST_OPTION_REASON,
+ isUnsupportedRequestOptionErrorMessage,
+} from '../shared/unsupported-request-option-error.js';
import { isNetworkishErrorMessage, PI_GATEWAY_DROP_REASON } from '../shared/network-error.js';
import { isContextModeDoctorToolName } from './context-mode-doctor-path.js';
import type { PiRpcEvent } from './rpc-client.js';
@@ -82,9 +86,10 @@ interface PiAssistantMessage {
interface PiPendingAssistantError {
message: string;
sdkError: string;
+ piCacheCompatibility?: import('./cache-compatibility.js').PiCacheCompatibility;
errorStatus?: 401 | 429 | 529;
usageLimit?: true;
- reason?: typeof CONTEXT_OVERFLOW_REASON | typeof UPSTREAM_STREAM_INTERRUPTED_REASON | typeof PI_GATEWAY_DROP_REASON;
+ reason?: typeof CONTEXT_OVERFLOW_REASON | typeof UPSTREAM_STREAM_INTERRUPTED_REASON | typeof PI_GATEWAY_DROP_REASON | typeof UNSUPPORTED_REQUEST_OPTION_REASON;
}
interface PiThinkingBlock {
@@ -94,6 +99,8 @@ interface PiThinkingBlock {
}
export interface PiTranslateContext {
+ getCacheCompatibility?: () => import('./cache-compatibility.js').PiCacheCompatibility | undefined;
+ cacheRecoveryHasOutput?: boolean;
logger: Logger;
/** Host-owned live tariff selector fallback when the provider response has no accepted tier. */
getPriceVariant?: () => 'standard' | 'priority';
@@ -581,9 +588,11 @@ function piAssistantErrorOf(rawError: string): PiPendingAssistantError {
...(signals.usageLimit ? { usageLimit: true } : {}),
...(isContextOverflowErrorMessage(redactedError)
? { reason: CONTEXT_OVERFLOW_REASON }
- : isStreamInterruptedErrorMessage(redactedError) || isPiAbortedRequest(redactedError)
- ? { reason: UPSTREAM_STREAM_INTERRUPTED_REASON }
- : {}),
+ : isUnsupportedRequestOptionErrorMessage(redactedError)
+ ? { reason: UNSUPPORTED_REQUEST_OPTION_REASON }
+ : isStreamInterruptedErrorMessage(redactedError) || isPiAbortedRequest(redactedError)
+ ? { reason: UPSTREAM_STREAM_INTERRUPTED_REASON }
+ : {}),
};
}
@@ -674,6 +683,7 @@ export function translatePiEvent(
switch (event.type) {
case 'agent_start': {
ctx.turnGeneration += 1;
+ ctx.cacheRecoveryHasOutput = false;
ctx.pendingHostTurnStartToken = null;
if (ctx.hostAbortRequestGeneration !== ctx.turnGeneration) {
clearPiHostAbortRequests(ctx);
@@ -732,6 +742,7 @@ export function translatePiEvent(
case 'message_update': {
const delta = event.assistantMessageEvent as Record<string, unknown> | undefined;
if (!delta || typeof delta.type !== 'string') return;
+ if (['text_delta', 'thinking_delta', 'toolcall_start', 'toolcall_delta'].includes(delta.type)) ctx.cacheRecoveryHasOutput = true;
observePiTokenSpeed(delta, queue, ctx);
handleAssistantDelta(delta, queue, ctx);
return;
@@ -773,6 +784,7 @@ export function translatePiEvent(
ctx.generationTimingReliable = false;
}
const fullText = assistantTextOf(message);
+ if (fullText.length > 0 || message.content?.some((block) => block.type === 'thinking' || block.type === 'toolCall')) ctx.cacheRecoveryHasOutput = true;
ctx.finalAssistantStopReason = typeof message.stopReason === 'string'
? message.stopReason
: null;
@@ -783,6 +795,10 @@ export function translatePiEvent(
if (transientAssistantFailure) {
const rawError = message.errorMessage?.trim() || fullText.trim() || 'Pi agent request failed';
ctx.pendingAssistantError = piAssistantErrorOf(rawError);
+ if (ctx.pendingAssistantError.reason === UNSUPPORTED_REQUEST_OPTION_REASON) {
+ const receipt = ctx.getCacheCompatibility?.();
+ if (receipt) ctx.pendingAssistantError.piCacheCompatibility = { ...receipt };
+ }
} else {
// A normal assistant message proves an earlier provider failure recovered.
ctx.pendingAssistantError = null;
@@ -811,6 +827,7 @@ export function translatePiEvent(
}
case 'tool_execution_start': {
+ ctx.cacheRecoveryHasOutput = true;
const toolUseId = String(event.toolCallId ?? '');
const toolName = String(event.toolName ?? 'tool');
const toolArgs = (event.args as Record<string, unknown>) ?? {};
@@ -1018,6 +1035,7 @@ export function translatePiEvent(
type: 'error',
data: {
...terminalError,
+ piCacheRecoverySafe: ctx.cacheRecoveryHasOutput === false,
isTerminal: true,
},
source: 'pi',
@@ -1144,6 +1162,10 @@ export function translatePiEvent(
type: 'error',
data: {
...finalError,
+ ...(finalError.reason === UNSUPPORTED_REQUEST_OPTION_REASON ? {
+ piCacheCompatibility: ctx.getCacheCompatibility?.(),
+ piCacheRecoverySafe: ctx.cacheRecoveryHasOutput === false,
+ } : {}),
isTerminal: true,
...(exhaustedReason ? { reason: exhaustedReason } : {}),
},
diff --git a/packages/maker-core/src/agents/shared/unsupported-request-option-error.test.ts b/packages/maker-core/src/agents/shared/unsupported-request-option-error.test.ts
new file mode 100644
index 0000000000..5fb84f5eba
--- /dev/null
+++ b/packages/maker-core/src/agents/shared/unsupported-request-option-error.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+ UNSUPPORTED_REQUEST_OPTION_REASON,
+ isUnsupportedRequestOptionErrorMessage,
+ unsupportedRequestOptionCompatOverride,
+} from './unsupported-request-option-error.js';
+
+// 真实形态(2026-09-20,Console Go / opencode-go + glm-5.3-flash)。
+const CONSOLE_GO_REJECTION =
+ '400: {"param":"prompt_cache_retention","type":"invalid_request_error","message":'
+ + '"Error from provider (Console Go): Upstream request failed: [invalid_request_error] '
+ + '\\"prompt_cache_retention\\" is not supported by this endpoint; use \\"prompt_cache_options\\""}';
+
+describe('unsupported request option error', () => {
+ it('classifies the Console Go prompt_cache_retention rejection and maps the compat fix', () => {
+ expect(isUnsupportedRequestOptionErrorMessage(CONSOLE_GO_REJECTION)).toBe(true);
+ expect(unsupportedRequestOptionCompatOverride(CONSOLE_GO_REJECTION)).toEqual({
+ supportsLongCacheRetention: false,
+ });
+ expect(UNSUPPORTED_REQUEST_OPTION_REASON).toBe('unsupported-request-option');
+ });
+
+ it('accepts an upstream that phrases the same rejection without the HTTP prefix', () => {
+ expect(
+ isUnsupportedRequestOptionErrorMessage(
+ 'invalid_request_error: prompt_cache_retention is unsupported here, use prompt_cache_options',
+ ),
+ ).toBe(true);
+ });
+
+ // issue #5878(2026-10-12):政企/内网自定义 OpenAI 兼容网关只点名 prompt_cache_key。
+ // Pi 1.0.2 的特殊 URL 还需要精确路由 hook;真实 native integration 覆盖该差异。
+ const CUSTOM_GATEWAY_KEY_REJECTION =
+ '400: {"message":"Validation: Unsupported parameter(s): `prompt_cache_key`",'
+ + '"type":"invalid_request_error"}';
+
+ it('classifies a custom gateway prompt_cache_key rejection and maps the same compat fix', () => {
+ expect(isUnsupportedRequestOptionErrorMessage(CUSTOM_GATEWAY_KEY_REJECTION)).toBe(true);
+ expect(unsupportedRequestOptionCompatOverride(CUSTOM_GATEWAY_KEY_REJECTION)).toEqual({
+ supportsLongCacheRetention: false,
+ });
+ });
+
+ it('accepts a prompt_cache_key rejection without markup or a suggested field', () => {
+ expect(
+ isUnsupportedRequestOptionErrorMessage('Unsupported parameter(s): prompt_cache_key'),
+ ).toBe(true);
+ expect(
+ isUnsupportedRequestOptionErrorMessage(
+ '400: {"param":"prompt_cache_key","message":"prompt_cache_key is not supported by this endpoint"}',
+ ),
+ ).toBe(true);
+ });
+
+ it.each([
+ ['generic invalid request', '400: {"error":{"message":"invalid api key"}}'],
+ ['rate limit', '429: rate limit exceeded, retry later'],
+ ['overload', 'overloaded_error: upstream is busy'],
+ ['only the suggested field', 'prompt_cache_options is not supported by this endpoint'],
+ ['only the rejected field, no verdict', 'request field prompt_cache_retention was forwarded'],
+ // 点名了别的参数:即使提到 prompt_cache_key 也不算(param 点名另一字段时同样拒绝)。
+ ['unsupported parameter that is not a cache field', 'Unsupported parameter(s): `temperature`'],
+ ['near-miss field name', 'Unsupported parameter(s): `prompt_cache_keyword`'],
+ [
+ 'structured param names another cache-related field',
+ '400: {"param":"prompt_cache_options","message":"Unsupported parameter(s): `prompt_cache_key`"}',
+ ],
+ // 裸 invalid_request_error 不再算「不支持」;结构化 param 不点名被拒字段也不算。
+ [
+ 'generic invalid_request_error mentioning both fields',
+ '400: {"type":"invalid_request_error","message":"prompt_cache_retention conflicts with prompt_cache_options"}',
+ ],
+ [
+ 'structured param names another field',
+ '400: {"param":"prompt_cache_options","type":"invalid_request_error","message":"prompt_cache_retention is not supported by this endpoint; use prompt_cache_options"}',
+ ],
+ ['empty', ''],
+ ])('does not classify %s as a self-heal target', (_label, message) => {
+ expect(isUnsupportedRequestOptionErrorMessage(message)).toBe(false);
+ expect(unsupportedRequestOptionCompatOverride(message)).toBeUndefined();
+ });
+});
+
+it.each([
+ '401: Unsupported parameter(s): prompt_cache_key',
+ '429: prompt_cache_key is not supported',
+ '400: {"error":{"param":"temperature","message":"Unsupported parameter(s): prompt_cache_key"}}',
+ '400: {"type":"authentication_error","message":"Unsupported parameter(s): prompt_cache_key"}',
+ 'temperature is unsupported; prompt_cache_key was forwarded',
+ 'Unsupported parameter(s): temperature; prompt_cache_key was forwarded',
+ '400: {broken: Unsupported parameter(s): prompt_cache_key',
+])('does not infer cache support from unrelated or ambiguous failure: %s', (message) => {
+ expect(isUnsupportedRequestOptionErrorMessage(message)).toBe(false);
+});
diff --git a/packages/maker-core/src/agents/shared/unsupported-request-option-error.ts b/packages/maker-core/src/agents/shared/unsupported-request-option-error.ts
new file mode 100644
index 0000000000..bbdd997163
--- /dev/null
+++ b/packages/maker-core/src/agents/shared/unsupported-request-option-error.ts
@@ -0,0 +1,64 @@
+/**
+ * Upstream 对「可选的请求增强字段」的确定性拒收(invalid_request_error)。
+ *
+ * 已确认的两种形态:
+ * 1. Console Go / OpenCode Zen-Go 的 GLM 上游(2026-09-20):
+ * `"prompt_cache_retention" is not supported by this endpoint; use "prompt_cache_options"`。
+ * 2. 政企/内网自定义 OpenAI 兼容网关(issue #5878,2026-10-12,Pi 1.0.2 实测复现):
+ * `Validation: Unsupported parameter(s): `prompt_cache_key``。
+ *
+ * 两种都是 400 而非网络/容量问题,原样重试必败;恢复动作是让 host 记住该 provider/model
+ * 不接受该字段,改写 models.json 的 compat 后重放同一轮请求(PI provider compat 自愈)。
+ *
+ * 判据只认「被点名的可选字段 + 明确的 not supported/unsupported 措辞」同时出现:
+ * 普通 400(鉴权/参数值错误/未点名已知字段)不满足;结构化错误里出现 `param` 时,
+ * 它必须点名这两类字段之一,避免把别的参数错误误判成「不支持」。
+ */
+export const UNSUPPORTED_REQUEST_OPTION_REASON = 'unsupported-request-option';
+
+/**
+ * `PI_CACHE_RETENTION=long` 下 Pi 会一起发给 openai-completions 端点的两个字段:
+ * 档位本身(prompt_cache_retention)与随之派生的路由键(prompt_cache_key)。
+ * Pi 1.0.2 普通 URL 下 compat 会移除二者;包含 api.openai.com 的 URL 仍可发送 key。
+ * Host 同时为精确命中的路由生成请求 hook 规则;真实 RPC/HTTP 回归覆盖两种 URL。
+ */
+const CACHE_FIELDS = ['prompt_cache_retention', 'prompt_cache_key'] as const;
+// `\b` 边界防止误匹配 prompt_cache_keyword / prompt_cache_retention_policy 之类的长字段。
+const CACHE_FIELD_RE = /\bprompt_cache_(?:retention|key)\b/i;
+// A relationship in the same short clause, not two keywords anywhere in the error.
+const REJECTED_FIELD_RE = /(?:unsupported\s+(?:request\s+)?parameters?(?:\(s\))?\s*:\s*[\x60"'\\\s]*(prompt_cache_(?:retention|key))\b|\b(prompt_cache_(?:retention|key))\b[\x60"'\\\s]*(?:is\s+(?:not\s+supported|unsupported)|isn't\s+supported))/i;
+
+export function isUnsupportedRequestOptionErrorMessage(message: string): boolean {
+ if (typeof message !== 'string' || message.length === 0 || message.length > 64 * 1024) return false;
+ const status = /^\s*(\d{3})\s*:/.exec(message);
+ if (status && status[1] !== '400') return false;
+ let text = message;
+ const jsonStart = message.indexOf('{');
+ if (jsonStart >= 0) {
+ try {
+ let value: unknown = JSON.parse(message.slice(jsonStart));
+ for (let depth = 0; depth < 3; depth++) {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+ const error = value as Record<string, unknown>;
+ if (Object.hasOwn(error, 'param') && !CACHE_FIELDS.some((field) => field === error.param)) return false;
+ if (error.type !== undefined && !['invalid_request_error', 'unsupported_parameter'].includes(String(error.type))) return false;
+ if (typeof error.message === 'string') { text = error.message; break; }
+ value = error.error;
+ }
+ } catch { return false; }
+ }
+ return CACHE_FIELD_RE.test(text) && REJECTED_FIELD_RE.test(text);
+}
+
+/**
+ * 该错误在 PI models.json compat 上的修正。目前只有一种形态:上游不接受缓存扩展字段,
+ * 关闭长缓存档位,并由精确路由的请求 hook 补齐残留字段处理。
+ * undefined = 没有已知修正,调用方不得自愈。
+ */
+export function unsupportedRequestOptionCompatOverride(
+ message: string,
+): { supportsLongCacheRetention: false } | undefined {
+ return isUnsupportedRequestOptionErrorMessage(message)
+ ? { supportsLongCacheRetention: false }
+ : undefined;
+}