fix(providers): inject top-level instructions for openai-responses wire (#134) (#160)

## Summary

- Strict OpenAI-Responses gateways (sub2api-style routers) return 400
when `input[]` carries a `system`/`developer` role without a matching
top-level `instructions` field. pi-ai's plain `openai-responses` wire
emits the former but not the latter.
- Mirror the `openai-codex-responses` wire's strict behavior via pi-ai's
`onPayload` hook: set `params.instructions` from the aggregated
systemPrompt, and filter out `role === "system" | "developer"` entries
from `input[]`.
- Only wired when `model.api === "openai-responses"` AND systemPrompt is
non-empty. Other wires (anthropic-messages, openai-completions,
openai-codex-responses) are untouched.

Fixes #134.

### Four principles

- Compatibility: green — no schema or IPC change; only the wire payload
for openai-responses is adjusted; other wires unchanged.
- Upgradeability: green — the filter/inject is local to `complete()`; if
pi-ai later emits `instructions` natively we can delete the hook in one
place.
- No bloat: green — ~20 lines, no new deps, reuses existing
`toPiContext` output (no helper refactor).
- Elegance: green — contract mirrors how `openai-codex-responses`
already behaves upstream.

## Test plan

- [x] `pnpm --filter @open-codesign/providers test -- --run` (10 files,
134 tests, incl. 3 new cases: payload mutation, no-op when systemPrompt
empty, no-op for anthropic wire)
- [x] `pnpm typecheck` (10/10 tasks successful)
- [x] `pnpm lint` (biome clean)
- [ ] Manual: call an openai-responses gateway that requires
`instructions` and confirm 200 with system prompt honored

Signed-off-by: hqhq1025 <1506751656@qq.com>

Author: hqhq1025

packages/providers/src/index.test.ts

@@ -304,3 +304,135 @@ describe('complete', () => {
     ).rejects.toMatchObject({ code: 'ATTACHMENT_TOO_LARGE' });
   });
 });
+
+describe('complete — openai-responses strict instructions', () => {
+  it('injects top-level instructions and strips system/developer input items via onPayload', async () => {
+    getModelMock.mockReturnValue({
+      id: 'gpt-5.1',
+      api: 'openai-responses',
+      provider: 'openai',
+    });
+
+    let capturedOnPayload:
+      | ((payload: unknown) => unknown | Promise<unknown | undefined>)
+      | undefined;
+
+    completeSimpleMock.mockImplementationOnce(async (_model, _context, opts) => {
+      capturedOnPayload = opts.onPayload;
+      return {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'ok' }],
+        api: 'openai-responses',
+        provider: 'openai',
+        model: 'gpt-5.1',
+        usage: {
+          input: 1,
+          output: 1,
+          cacheRead: 0,
+          cacheWrite: 0,
+          totalTokens: 2,
+          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+        stopReason: 'stop',
+        timestamp: Date.now(),
+      };
+    });
+
+    await complete(
+      { provider: 'openai', modelId: 'gpt-5.1' },
+      [
+        { role: 'system', content: 'You are open-codesign.' },
+        { role: 'user', content: 'hi' },
+      ],
+      { apiKey: 'sk-test' },
+    );
+
+    expect(capturedOnPayload).toBeDefined();
+
+    const params = {
+      input: [
+        { role: 'system', content: 'ignored' },
+        { role: 'developer', content: 'ignored' },
+        { role: 'user', content: [{ type: 'input_text', text: 'hi' }] },
+      ],
+    };
+    const mutated = (await capturedOnPayload?.(params)) as {
+      instructions?: string;
+      input: Array<{ role: string }>;
+    };
+
+    expect(mutated.instructions).toBe('You are open-codesign.');
+    expect(mutated.input.map((entry) => entry.role)).toEqual(['user']);
+  });
+
+  it('does not attach onPayload when systemPrompt is empty', async () => {
+    getModelMock.mockReturnValue({
+      id: 'gpt-5.1',
+      api: 'openai-responses',
+      provider: 'openai',
+    });
+
+    completeSimpleMock.mockImplementationOnce(async (_model, _context, opts) => {
+      expect(opts.onPayload).toBeUndefined();
+      return {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'ok' }],
+        api: 'openai-responses',
+        provider: 'openai',
+        model: 'gpt-5.1',
+        usage: {
+          input: 1,
+          output: 1,
+          cacheRead: 0,
+          cacheWrite: 0,
+          totalTokens: 2,
+          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+        stopReason: 'stop',
+        timestamp: Date.now(),
+      };
+    });
+
+    await complete({ provider: 'openai', modelId: 'gpt-5.1' }, [{ role: 'user', content: 'hi' }], {
+      apiKey: 'sk-test',
+    });
+  });
+
+  it('does not attach onPayload for anthropic-messages wire even with systemPrompt', async () => {
+    getModelMock.mockReturnValue({
+      id: 'claude-4.7-sonnet',
+      api: 'anthropic-messages',
+      provider: 'anthropic',
+    });
+
+    completeSimpleMock.mockImplementationOnce(async (_model, _context, opts) => {
+      expect(opts.onPayload).toBeUndefined();
+      return {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'ok' }],
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        model: 'claude-4.7-sonnet',
+        usage: {
+          input: 1,
+          output: 1,
+          cacheRead: 0,
+          cacheWrite: 0,
+          totalTokens: 2,
+          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+        stopReason: 'stop',
+        timestamp: Date.now(),
+      };
+    });
+
+    await complete(
+      { provider: 'anthropic', modelId: 'claude-4.7-sonnet' },
+      [
+        { role: 'system', content: 'You are open-codesign.' },
+        { role: 'user', content: 'hi' },
+      ],
+      { apiKey: 'sk-ant-test' },
+    );
+  });
+});

packages/providers/src/index.ts

@@ -233,6 +233,7 @@ export async function complete(
         maxTokens?: number;
         reasoning?: ReasoningLevel;
         headers?: Record<string, string>;
+        onPayload?: (payload: unknown) => unknown;
       },
     ) => Promise<PiAssistantMessage>;
   };
@@ -251,13 +252,16 @@ export async function complete(
     }
   }
 
+  const piContext = toPiContext(messages, piModel, opts);
+
   const piOpts: {
     apiKey: string;
     baseUrl?: string;
     signal?: AbortSignal;
     maxTokens?: number;
     reasoning?: ReasoningLevel;
     headers?: Record<string, string>;
+    onPayload?: (payload: unknown) => unknown;
   } = {
     apiKey,
   };
@@ -267,6 +271,28 @@ export async function complete(
   if (opts.reasoning !== undefined) piOpts.reasoning = opts.reasoning;
   if (opts.httpHeaders !== undefined) piOpts.headers = { ...opts.httpHeaders };
 
+  // Strict OpenAI-Responses gateways (e.g. sub2api-style routers) 400 when
+  // they see BOTH a system/developer item in `input[]` AND no top-level
+  // `instructions`. pi-ai's plain `openai-responses` wire injects the former
+  // but not the latter, so we mirror the codex wire's strict behavior here:
+  // set `instructions` and strip system/developer entries from `input[]`.
+  if (piModel.api === 'openai-responses' && piContext.systemPrompt) {
+    const systemPrompt = piContext.systemPrompt;
+    piOpts.onPayload = (payload) => {
+      const params = payload as {
+        instructions?: string;
+        input?: Array<{ role?: string }>;
+      };
+      params.instructions = systemPrompt;
+      if (Array.isArray(params.input)) {
+        params.input = params.input.filter(
+          (entry) => entry.role !== 'system' && entry.role !== 'developer',
+        );
+      }
+      return params;
+    };
+  }
+
   // sub2api / claude2api gateways 403 requests without claude-cli identity
   // headers. pi-ai only injects those on OAuth tokens — paste a
   // sub2api-issued key and you hit the plain API-key branch. Force the
@@ -280,7 +306,7 @@ export async function complete(
   }
 
   validateCodexImageInputs(opts);
-  const result = await pi.completeSimple(piModel, toPiContext(messages, piModel, opts), piOpts);
+  const result = await pi.completeSimple(piModel, piContext, piOpts);
 
   if (result.stopReason === 'error') {
     throw new CodesignError(