Deploy 7af3d19 to Docker Space

Source: MisonL/gpt-image-playground-customer@7af3d19e476e03dfd25eef49672c982b46c64be8

README.md

@@ -279,7 +279,7 @@ node skills/gpt-image-playground-agent/scripts/diagnose-request.mjs \
 - 远程 Space、云服务或内网服务必须显式传 `--base-url`，避免误用本机默认服务。
 - Agent CLI 默认读取当前仓库根目录的 `.env.agent.local`；shell 环境变量优先。首次配置可复制 `.env.agent.local.example`。不要提交 token、访问码或哈希。
 - `GPT_IMAGE_AGENT_TOKEN` 只用于 `/api/agent/*`；页面 SSE `/api/images` 可能还需要 `GPT_IMAGE_APP_PASSWORD_HASH`。
-- dry-run 只验证本地请求构造；`verification_scope.mode=local_planning_only` 不是远端已可执行。远端合同检查用 `--contract-check`，真实执行必须加 `--allow-billable`。
+- dry-run 只验证本地请求构造；`verification_scope.mode=local_planning_only` 不是远端已可执行。需要只读读取远端 capabilities 和 runtime 时加 `--check-remote`，输出 `verification_scope.mode=remote_contract_and_local_planning`。远端合同检查用 `--contract-check`，真实执行必须加 `--allow-billable`。
 - 多张真实任务优先用 `batch-images.mjs`、`--manifest`、`--resume` 和 `--dimension-check`；不要手动并行启动多个单张脚本。需要并发时先看 `/api/runtime-capabilities` 的 `streamingBatch.recommendedConcurrency` 和 `channelQueue.capacityPerCredential`。
 - 选择 `responses-image-generation` 或兼容别名 `responses` 时，`partial_images` 必须优先按 `partial_images_by_backend["responses-image-generation"]` 校验，不能套用 Matsca Images API 的范围。
 - 页面 SSE 返回 503 或断流时，先用诊断脚本读取结构化摘要，再用新的幂等键显式选择备用路径。`page_sse_supported=true` 只是声明支持，不代表实测一定成功。Agent edit 输出格式和尺寸可能与页面 SSE 不完全一致，尺寸敏感任务必须重新校验或用 `--dimension-check`。

docs/deployment/huggingface-space-free.md

@@ -199,7 +199,7 @@ node skills/gpt-image-playground-agent/scripts/generate-image.mjs \
 
 脚本会先读取 `GET /api/agent/capabilities`，再调用 Agent API。成功响应会保留相对 `content_url`，同时补充 `absolute_content_url` 和 `absolute_metadata_url`，便于在桌面环境直接下载产物。
 
-远端 Agent 调用不要硬编码路径。脚本会按 capabilities 中的 `routing_rules`、`agent_streaming` 和 `agent_jobs` 判断默认路径：普通小图走 Agent JSON，`max_edge>2048` 的单次文生图和高分辨率 edit 默认优先走页面端 `/api/images` SSE；页面流式失败或不可用时，先诊断结构化错误，再显式回退到 Agent JSON、Agent edit 或 job 路径。job polling 只在显式选择时使用。需要诊断对照时可用 `--agent` 或 `--streaming-strategy off` 强制 Agent JSON，也可用 `--page-sse` 或 `--job` 显式选择路径。
+远端 Agent 调用不要硬编码路径。普通文生图默认提交业务意图到 capabilities 声明的 `orchestration.endpoint`，由服务端选择内部执行路径、上游 request mode 和轮询方式；Agent 客户端不按尺寸、远端 HTTPS 或流式参数自行选择 Images、Responses、SSE 或非流式路径。页面高级字段、默认 WebP edit、高分辨率 edit 和复杂批量仍按 Skill 规则使用页面端 `/api/images` SSE；页面流式失败或不可用时，先诊断结构化错误，再用新的 `Idempotency-Key` 显式选择 Agent JSON、Agent edit 或 job 路径对照。job polling 只在显式选择时使用。需要诊断对照时可用 `--agent` 或 `--streaming-strategy off` 强制 Agent JSON，也可用 `--page-sse` 或 `--job` 显式选择路径。
 
 如果 Space 同时配置了 `APP_PASSWORD` 和 `AGENT_API_TOKEN`，Agent JSON 端点用 `GPT_IMAGE_AGENT_TOKEN` 发送 Bearer token；页面端 `/api/images` SSE 仍按 capabilities 的 `agent_streaming.page_sse.auth` 判断，可能需要额外设置 `GPT_IMAGE_APP_PASSWORD_HASH`，并通过 form-data `passwordHash` 发送页面访问码哈希。页面 SSE 会把业务 key 写入 `clientRequestId`，长度上限以 capabilities 中的 `agent_streaming.page_sse.client_request_id.max_length` 为准。
 

public/hf-space-deploy-marker.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "local_sha": "34544ccd35f4321f92ab73ef5ac36603ee9f7720",
-  "created_at": "2026-06-24T14:38:59.964Z",
-  "deploy_id": "dee10b1a-4b9c-47bb-a7f3-89875a64183f"
+  "local_sha": "7af3d19e476e03dfd25eef49672c982b46c64be8",
+  "created_at": "2026-06-26T01:06:33.777Z",
+  "deploy_id": "46b8343b-982b-4f3b-8526-ca1feabfd227"
 }

scripts/agent-doctor.mjs

@@ -391,6 +391,10 @@ function buildSummary({ capabilities, runtime, contract, smoke }) {
             runtime: runtime.ok ? runtime.body : undefined,
             smoke
         }),
+        runtime_environment: buildRuntimeEnvironmentSummary({
+            capabilities: capabilities.ok ? capabilities.body : undefined,
+            runtime: runtime.ok ? runtime.body : undefined
+        }),
         responses_gpt2image_ready:
             capabilities.ok && runtime.ok
                 ? capabilities.body?.supported?.image_backend_requirements?.['responses-image-generation']?.enabled === true &&
@@ -403,6 +407,26 @@ function buildSummary({ capabilities, runtime, contract, smoke }) {
     };
 }
 
+function buildRuntimeEnvironmentSummary({ capabilities, runtime }) {
+    return {
+        state_backend: capabilities?.defaults?.state_backend || 'unknown',
+        image_storage_mode: capabilities?.storage?.image_storage_mode || 'unknown',
+        postgres_configured: capabilities?.storage?.postgres_configured === true,
+        page_sse_auth_required: capabilities?.agent_streaming?.page_sse?.auth?.required === true,
+        agent_auth_schemes: Array.isArray(capabilities?.auth?.schemes) ? capabilities.auth.schemes : [],
+        orchestration_endpoint: capabilities?.orchestration?.endpoint || null,
+        orchestration_transport_selection: capabilities?.orchestration?.transport_selection || null,
+        request_mode_control_policy: capabilities?.request_mode_controls?.agent_client_policy || null,
+        request_mode_controls: runtime?.channelRouting?.requestModeControls || capabilities?.request_mode_controls || null,
+        runtime_strategy: runtime?.channelRouting?.strategy || null,
+        effective_request_modes: readRequestModeList(runtime?.channelRouting?.effectiveRequestModes),
+        streaming_batch_enabled: runtime?.streamingBatch?.enabled === true,
+        recommended_concurrency: runtime?.streamingBatch?.recommendedConcurrency ?? null,
+        channel_queue_enabled: runtime?.channelQueue?.enabled === true,
+        channel_queue_capacity_per_credential: runtime?.channelQueue?.capacityPerCredential ?? null
+    };
+}
+
 function summarizeSmokeCheck(smoke, name) {
     const check = smoke.checks?.find((item) => item.name === name);
     if (!check || check.skipped) return 'skipped';

scripts/agent-skill-scripts.test.mjs

@@ -618,6 +618,18 @@ describe('Agent skill script argument validation', () => {
         assert.equal(result.stderr.trim(), '');
     });
 
+    it('explains explicit page SSE dry-runs without blaming high-resolution routing', () => {
+        const result = runSkillScript('generate-image.mjs', ['--page-sse', '--size', '1024x1024', 'prompt']);
+
+        assert.equal(result.status, 0);
+        const body = JSON.parse(result.stdout);
+        assert.equal(body.endpoint, 'http://localhost:4783/api/images');
+        assert.equal(body.routing_guidance.transport, 'page_sse');
+        assert.match(body.routing_guidance.reason, /Explicit --page-sse/);
+        assert.doesNotMatch(body.routing_guidance.reason, /max_edge>2048/);
+        assert.equal(result.stderr.trim(), '');
+    });
+
     it('prints server orchestration guidance for remote HTTPS small generate dry-runs', () => {
         const result = runSkillScript('generate-image.mjs', ['--base-url', 'https://space.example.test', 'prompt']);
 
@@ -631,6 +643,70 @@ describe('Agent skill script argument validation', () => {
         assert.equal(result.stderr.trim(), '');
     });
 
+    it('can combine generate dry-run planning with non-billable remote checks', async () => {
+        const requests = [];
+        await withServer(
+            (request, response) => {
+                requests.push({ method: request.method, url: request.url });
+                if (request.url === '/api/agent/capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify(
+                            agentGenerateCapabilities({
+                                supported: {
+                                    request_modes: ['images-non-stream', 'images-sse']
+                                },
+                                agent_streaming: {
+                                    page_sse: { supported: true, endpoint: '/api/images' }
+                                }
+                            })
+                        )
+                    );
+                    return;
+                }
+                if (request.url === '/api/runtime-capabilities') {
+                    response.writeHead(200, { 'content-type': 'application/json' });
+                    response.end(
+                        JSON.stringify({
+                            streamingBatch: { enabled: true, recommendedConcurrency: 2 },
+                            channelRouting: { effectiveRequestModes: ['images-non-stream'] }
+                        })
+                    );
+                    return;
+                }
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing' }));
+            },
+            async (baseUrl) => {
+                const result = await runSkillScriptAsync(
+                    'generate-image.mjs',
+                    ['--check-remote', 'prompt'],
+                    { GPT_IMAGE_PLAYGROUND_URL: baseUrl }
+                );
+
+                assert.equal(result.status, 0);
+                assert.equal(result.stderr.trim(), '');
+                const body = JSON.parse(result.stdout);
+                assert.equal(body.verification_scope.mode, 'remote_contract_and_local_planning');
+                assert.equal(body.verification_scope.remote_capabilities_verified, true);
+                assert.equal(body.verification_scope.runtime_capacity_verified, true);
+                assert.equal(body.verification_scope.auth_verified, true);
+                assert.equal(body.verification_scope.billable_request_sent, false);
+                assert.deepEqual(body.verification_scope.remote_check.capabilities.request_modes, [
+                    'images-non-stream',
+                    'images-sse'
+                ]);
+                assert.deepEqual(body.verification_scope.remote_check.runtime.effective_request_modes, [
+                    'images-non-stream'
+                ]);
+                assert.deepEqual(
+                    requests.map((item) => `${item.method} ${item.url}`),
+                    ['GET /api/agent/capabilities', 'GET /api/runtime-capabilities']
+                );
+            }
+        );
+    });
+
     it('keeps default generate on server orchestration when request modes are declared', async () => {
         const requests = [];
         let imageRequestBody = '';
@@ -789,7 +865,19 @@ describe('Agent skill script argument validation', () => {
                 requests.push({ method: request.method, url: request.url });
                 if (request.url === '/api/agent/capabilities') {
                     response.writeHead(200, { 'content-type': 'application/json' });
-                    response.end(JSON.stringify(agentGenerateCapabilities()));
+                    response.end(
+                        JSON.stringify(
+                            agentGenerateCapabilities({
+                                agent_streaming: {
+                                    page_sse: {
+                                        supported: true,
+                                        endpoint: '/api/images',
+                                        client_request_id: { max_length: 128 }
+                                    }
+                                }
+                            })
+                        )
+                    );
                     return;
                 }
                 if (
@@ -809,6 +897,11 @@ describe('Agent skill script argument validation', () => {
                     );
                     return;
                 }
+                if (request.url === '/api/images') {
+                    response.writeHead(400, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'clientRequestId 长度不能超过 128 个字符。' }));
+                    return;
+                }
                 response.writeHead(404, { 'content-type': 'application/json' });
                 response.end(JSON.stringify({ error: 'missing' }));
             },
@@ -827,7 +920,8 @@ describe('Agent skill script argument validation', () => {
                     [
                         '/api/agent/images/generate',
                         '/api/agent/image-requests',
-                        '/api/agent/jobs/images/generate'
+                        '/api/agent/jobs/images/generate',
+                        '/api/images'
                     ]
                 );
                 assert.deepEqual(
@@ -836,7 +930,8 @@ describe('Agent skill script argument validation', () => {
                         'GET /api/agent/capabilities',
                         'POST /api/agent/images/generate',
                         'POST /api/agent/image-requests',
-                        'POST /api/agent/jobs/images/generate'
+                        'POST /api/agent/jobs/images/generate',
+                        'POST /api/images'
                     ]
                 );
             }
@@ -3618,6 +3713,8 @@ describe('Agent skill script argument validation', () => {
         assert.match(skillText, /Codex 会话日志会持久保存命令输出/);
         assert.match(skillText, /npm run env:summary/);
         assert.match(skillText, /verification_scope\.mode=local_planning_only/);
+        assert.match(skillText, /--check-remote/);
+        assert.match(skillText, /remote_contract_and_local_planning/);
         assert.match(skillText, /manifest_written=false/);
         assert.match(skillText, /Hugging Face Space Secrets 只能写入和列出名称/);
 
@@ -3628,6 +3725,8 @@ describe('Agent skill script argument validation', () => {
         assert.match(apiReference, /channel_capacity_queue_aborted/);
         assert.match(apiReference, /npm run env:summary/);
         assert.match(apiReference, /verification_scope\.mode=local_planning_only/);
+        assert.match(apiReference, /--check-remote/);
+        assert.match(apiReference, /remote_contract_and_local_planning/);
         assert.match(apiReference, /manifest_written=false/);
         assert.match(apiReference, /Hugging Face Space Secrets 只能写入和列出名称/);
         assert.match(apiReference, /这个失败表示上游已生成但本地验收未通过/);
@@ -3831,6 +3930,25 @@ describe('Agent skill script argument validation', () => {
         }
     });
 
+    it('prints stdin batch dry-run plans without inventing a /dev/stdin manifest path', () => {
+        const input = `${JSON.stringify({
+            id: 'stdin-task',
+            prompt: 'stdin prompt',
+            size: '1024x1024'
+        })}\n`;
+
+        const result = runSkillScript('batch-images.mjs', ['--input', '-'], {}, { input });
+
+        assert.equal(result.status, 0);
+        assert.equal(result.stderr.trim(), '');
+        const body = JSON.parse(result.stdout);
+        assert.equal(body.input, '/dev/stdin');
+        assert.equal(body.manifest, null);
+        assert.equal(body.manifest_written, false);
+        assert.equal(body.total, 1);
+        assert.equal(body.tasks[0].id, 'stdin-task');
+    });
+
     it('records enriched Agent diagnostics for failed batch tasks and manifests', async () => {
         const tempRoot = mkdtempSync(join(tmpdir(), 'gpt-image-batch-diagnostics-'));
         try {
@@ -5990,6 +6108,9 @@ describe('Agent skill script argument validation', () => {
                 assert.equal(result.stderr.trim(), '');
                 const body = JSON.parse(result.stdout);
                 assert.equal(body.client_request_id, 'web-diag');
+                assert.equal(body.found, true);
+                assert.equal(body.page_request_query_count, 1);
+                assert.equal(body.page_request_found_count, 1);
                 assert.equal(body.feedback.value, 'usable');
                 assert.equal(body.diagnostics.matched_log_count, 1);
                 assert.equal(body.request_count, 1);
@@ -6479,7 +6600,11 @@ describe('Agent skill script argument validation', () => {
                 assert.equal(result.stderr.trim(), '');
                 const body = JSON.parse(result.stdout);
                 assert.deepEqual(body.diagnostics_retention, retention);
+                assert.equal(body.found, false);
+                assert.equal(body.page_request_query_count, 1);
+                assert.equal(body.page_request_found_count, 0);
                 assert.equal(body.diagnostics_note.code, 'no_matching_logs_in_retention_window');
+                assert.equal(body.requests[0].found, false);
                 assert.equal(body.requests[0].diagnostics_note.code, 'no_matching_logs_in_retention_window');
                 assert.equal(body.requests[0].diagnostics_note.retention.max_entries, 123);
                 assert.match(body.requests[0].diagnostics_note.message, /最近 123 条本地应用日志/);
@@ -6570,7 +6695,8 @@ function runSkillScript(filename, args, env = {}, options = {}) {
     return spawnSync(process.execPath, [join(skillScriptsRoot, filename), ...args], {
         cwd: options.cwd || repoRoot,
         encoding: 'utf8',
-        env: { ...baseEnv, ...env }
+        env: { ...baseEnv, ...env },
+        ...(options.input !== undefined ? { input: options.input } : {})
     });
 }
 

scripts/command-center.test.mjs

@@ -752,6 +752,11 @@ describe('Command center scripts', () => {
                                 endpoint: '/api/agent/image-requests',
                                 transport_selection: 'server_owned'
                             },
+                            request_mode_controls: {
+                                global_env: 'OPENAI_UPSTREAM_REQUEST_MODES',
+                                channel_env_pattern: 'OPENAI_CHANNEL_N_REQUEST_MODES',
+                                agent_client_policy: 'diagnostics_only'
+                            },
                             routing_rules: {
                                 high_resolution_edit: {
                                     conditions: { operation: 'edit', max_edge: { operator: 'gt', value: 2048 } }
@@ -796,9 +801,16 @@ describe('Command center scripts', () => {
                                 defaultMode: 'auto',
                                 unavailableMarkScope: 'channel+backend+strategy+operation'
                             },
-                            streamingBatch: { enabled: true },
+                            streamingBatch: { enabled: true, recommendedConcurrency: 2 },
+                            channelQueue: { enabled: true, capacityPerCredential: 1 },
                             responsesImageBackend: { enabled: true, mode: 'experimental' },
                             channelRouting: {
+                                strategy: 'round_robin',
+                                requestModeControls: {
+                                    global_env: 'OPENAI_UPSTREAM_REQUEST_MODES',
+                                    channel_env_pattern: 'OPENAI_CHANNEL_N_REQUEST_MODES',
+                                    agent_client_policy: 'diagnostics_only'
+                                },
                                 configuredRequestModes: ['images-non-stream', 'images-sse', 'responses-sse'],
                                 effectiveRequestModes: ['images-non-stream', 'images-sse'],
                                 effectiveRequestModesByChannel: [
@@ -900,6 +912,27 @@ describe('Command center scripts', () => {
                 assert.equal(body.summary.request_modes.smoke['responses-sse'].billable, false);
                 assert.equal(body.summary.responses_gpt2image_ready, true);
                 assert.equal(body.summary.responses_image_backend_declared_supported, true);
+                assert.deepEqual(body.summary.runtime_environment, {
+                    state_backend: 'memory',
+                    image_storage_mode: 'indexeddb',
+                    postgres_configured: false,
+                    page_sse_auth_required: true,
+                    agent_auth_schemes: [],
+                    orchestration_endpoint: '/api/agent/image-requests',
+                    orchestration_transport_selection: 'server_owned',
+                    request_mode_control_policy: 'diagnostics_only',
+                    request_mode_controls: {
+                        global_env: 'OPENAI_UPSTREAM_REQUEST_MODES',
+                        channel_env_pattern: 'OPENAI_CHANNEL_N_REQUEST_MODES',
+                        agent_client_policy: 'diagnostics_only'
+                    },
+                    runtime_strategy: 'round_robin',
+                    effective_request_modes: ['images-non-stream', 'images-sse'],
+                    streaming_batch_enabled: true,
+                    recommended_concurrency: 2,
+                    channel_queue_enabled: true,
+                    channel_queue_capacity_per_credential: 1
+                });
                 assert.equal(body.summary.billable_smoke, 'skipped');
                 assert.equal(body.layers.find((layer) => layer.name === 'billable_smoke').skipped, true);
                 assert.ok(
@@ -1013,16 +1046,27 @@ describe('Command center scripts', () => {
                     return;
                 }
                 if (request.url === '/api/images') {
-                    response.writeHead(200, { 'content-type': 'text/event-stream' });
-                    response.end(
-                        [
-                            'data: {"type":"completed","filename":"doctor-page-sse.png","path":"/api/image/doctor-page-sse.png","output_format":"png"}',
-                            '',
-                            'data: {"type":"done","client_request_id":"doctor-page-sse-request","images":[{"filename":"doctor-page-sse.png"}]}',
-                            '',
-                            ''
-                        ].join('\n')
-                    );
+                    (async () => {
+                        const requestText = await readRequestText(request);
+                        if (requestText.includes('contract check')) {
+                            response.writeHead(400, { 'content-type': 'application/json' });
+                            response.end(JSON.stringify({ error: 'clientRequestId 长度不能超过 128 个字符。' }));
+                            return;
+                        }
+                        response.writeHead(200, { 'content-type': 'text/event-stream' });
+                        response.end(
+                            [
+                                'data: {"type":"completed","filename":"doctor-page-sse.png","path":"/api/image/doctor-page-sse.png","output_format":"png"}',
+                                '',
+                                'data: {"type":"done","client_request_id":"doctor-page-sse-request","images":[{"filename":"doctor-page-sse.png"}]}',
+                                '',
+                                ''
+                            ].join('\n')
+                        );
+                    })().catch((error) => {
+                        response.writeHead(500, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify({ error: error.message }));
+                    });
                     return;
                 }
                 if (request.url === '/api/agent/image-requests') {
@@ -1127,8 +1171,19 @@ describe('Command center scripts', () => {
                     return;
                 }
                 if (request.url === '/api/images') {
-                    response.writeHead(503, { 'content-type': 'text/plain' });
-                    response.end('503 Service temporarily unavailable');
+                    (async () => {
+                        const requestText = await readRequestText(request);
+                        if (requestText.includes('contract check')) {
+                            response.writeHead(400, { 'content-type': 'application/json' });
+                            response.end(JSON.stringify({ error: 'clientRequestId 长度不能超过 128 个字符。' }));
+                            return;
+                        }
+                        response.writeHead(503, { 'content-type': 'text/plain' });
+                        response.end('503 Service temporarily unavailable');
+                    })().catch((error) => {
+                        response.writeHead(500, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify({ error: error.message }));
+                    });
                     return;
                 }
                 if (request.url === '/api/agent/jobs/images/generate') {
@@ -1356,3 +1411,15 @@ function runNodeCommandAsync(args, options = {}) {
         });
     });
 }
+
+function readRequestText(request) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        request.setEncoding('utf8');
+        request.on('data', (chunk) => {
+            body += chunk;
+        });
+        request.on('end', () => resolve(body));
+        request.on('error', reject);
+    });
+}

skills/gpt-image-playground-agent/SKILL.md

@@ -19,7 +19,7 @@ Agent API 是给自动化客户端使用的机器接口，不是自治 Agent 平
 - 诊断上游图片接口：优先运行 `scripts/probe-upstream-image.mjs`。
 - 不要临时编写 Node/Python/shell 脚本、curl 命令或手写 fetch/FormData 来重复实现这些脚本已经覆盖的 API 调用。
 - 只有在内置脚本缺少用户明确需要的能力时，才修改或扩展 `scripts/` 内的预置脚本，并同步补测试；不要在仓库外留下 ad hoc 调用脚本。
-- 先用 dry-run 或 `--contract-check` 检查请求、路由、鉴权和服务声明的默认编排入口；只有用户明确允许真实计费时才加 `--allow-billable`。
+- 先用 dry-run、`--check-remote` 或 `--contract-check` 检查请求、路由、鉴权和服务声明的默认编排入口；只有用户明确允许真实计费时才加 `--allow-billable`。
 - 真实调用成功或失败后，优先读取脚本输出的 `summary`。它是面向 Agent 的机器摘要，包含 `billable`、请求 ID、幂等键、产物 URL、耗时、耗时拆分、路由、渠道、上游 host、脱敏请求头、重试和下一步动作；Agent JSON 失败时脚本会按幂等键做一次只读 Agent state 诊断补采样，补充 `agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status`、`request_id`、渠道和上游 host。不要再先手查 SQLite、Docker logs 或上游后台。
 - 新增 probe、diagnostics、路由健康或请求旅程能力时，先在服务端定义机器 API 契约，并通过 `GET /api/agent/capabilities`、`GET /api/agent/openapi.json` 或明确的 `/api/agent/diagnostics/*` 端点声明；Skill 脚本只做薄封装，不能复制页面 API、运行态 API 和 Agent API 的边界判断。
 
@@ -125,7 +125,7 @@ Authorization: Bearer <token>
 - `scripts/diagnose-request.mjs`：按一个或多个页面 `clientRequestId` 只读查询结果反馈和脱敏日志诊断摘要，也可按 Agent `request_id` 或 `idempotency_key` 查询 Agent state 请求诊断；支持读取批量 manifest 和 `--base-url`，不触发生图计费。
 - `scripts/probe-upstream-image.mjs`：直接探测上游图片接口连通性。默认只检查 DNS、TLS 和 `/models`，必须添加 `--allow-billable` 才会真实调用 `/images/generations`。
 
-生成、编辑和批量脚本的 dry-run 输出会包含 `verification_scope.mode=local_planning_only`，表示只验证了本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。生成 dry-run 默认 `routing_guidance.transport=server_orchestrated`，表示真实请求只提交业务意图到服务端编排入口；显式 `--agent`、`--job`、`--page-sse` 才会显示对应诊断路径。批量 dry-run 还会包含 `guardrails`，提示真实执行要复用同一个 `--ordered-prefix`，固定尺寸任务是否建议加 `--dimension-check`。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `route_decision`、`transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`；尺寸门禁失败时还会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`，便于人工审查。
+生成、编辑和批量脚本的 dry-run 输出会包含 `verification_scope.mode=local_planning_only`，表示只验证了本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。生成 dry-run 添加 `--check-remote` 后会只读查询 `/api/agent/capabilities` 和 `/api/runtime-capabilities`，输出 `verification_scope.mode=remote_contract_and_local_planning`，仍不会发送真实生图请求。生成 dry-run 默认 `routing_guidance.transport=server_orchestrated`，表示真实请求只提交业务意图到服务端编排入口；显式 `--agent`、`--job`、`--page-sse` 才会显示对应诊断路径。批量 dry-run 还会包含 `guardrails`，提示真实执行要复用同一个 `--ordered-prefix`，固定尺寸任务是否建议加 `--dimension-check`。真实执行输出会包含 `summary`；成功摘要含 `ok=true`、`billable`、`request_id`、`idempotency_key`、`artifact_ids`、`content_urls`、`absolute_content_urls`、`image_dimensions`、`actual_dimensions`、`cached`、`elapsed_ms`、`server_elapsed_ms`、`elapsed_source`、`elapsed_breakdown`、`transport`、`endpoint`、`route_mode`、`image_backend`、`stream_mode`、`streaming_strategy`、`channel_request_mode`、`channel_request_mode_fallback_applied`、`route_decision`、`selected_channel_id`、`upstream_host` 和脱敏 `request_headers`。失败摘要含 `route_decision`、`transport_error_kind`、`retry_after_ms`、`cooldown_until`、`cooldown_target`、`retryable`、`dimension_check_failed`、`expected_dimensions`、`actual_dimensions`、`agent_diagnostics_checked`、`agent_diagnostics_found`、`agent_diagnostics_unavailable_reason`、`agent_diagnostics_http_status` 和 `next_action`；尺寸门禁失败时还会保留已生成产物的 `artifact_ids`、`content_urls`、`absolute_content_urls` 和 `image_dimensions`，便于人工审查。
 所有生成、编辑、批量和探针脚本在 dry-run 或真实请求前都会校验尺寸参数。`gpt-image-2` 支持 `auto` 或任意正整数 `WIDTHxHEIGHT`；默认 OpenAI-compatible 上游的更严格尺寸边界由服务端 profile 或真实上游显式报错。非 `gpt-image-2` 模型只接受 `auto`、`1024x1024`、`1536x1024` 或 `1024x1536`。生成、页面编辑、批量页面 SSE 和上游探针默认请求 `output_format=webp`、`output_compression=100`；普通 Agent edit 不发送输出格式字段，输出格式固定为 Agent 契约。
 
 如果当前上下文位于仓库根目录，管理员侧优先使用顶层命令：

skills/gpt-image-playground-agent/references/api.md

@@ -29,9 +29,9 @@ Agent API 是给自动化客户端使用的机器接口，不是自治 Agent 平
 - `scripts/diagnose-request.mjs`：按页面 `clientRequestId` 只读查询结果反馈和脱敏日志诊断摘要，也可按 Agent `request_id` 或 `idempotency_key` 查询 Agent state 请求诊断，支持 `--base-url` 固定目标服务。
 - `scripts/probe-upstream-image.mjs`：上游图片接口连通性探针。
 
-生成、编辑和批量脚本默认只做 dry-run，不触发真实生图或编辑。dry-run 输出的 `verification_scope.mode=local_planning_only` 表示只完成本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。必须显式添加 `--allow-billable` 才会调用真实端点。generate 默认提交到 `/api/agent/image-requests` 服务端编排入口；`--agent`、`--job`、`--page-sse` 才会显式改用 `/api/agent/images/generate`、`/api/agent/jobs/images/generate` 或页面端 `/api/images` SSE。
+生成、编辑和批量脚本默认只做 dry-run，不触发真实生图或编辑。dry-run 输出的 `verification_scope.mode=local_planning_only` 表示只完成本地请求构造、参数归一化和静态路由规划；它不会读取远端 capabilities，不会验证远端鉴权、渠道容量或 manifest 写入。generate 可添加 `--check-remote` 做只读远端检查，输出 `verification_scope.mode=remote_contract_and_local_planning`，仅访问 `/api/agent/capabilities` 和 `/api/runtime-capabilities`，不会发送真实生图请求。必须显式添加 `--allow-billable` 才会调用真实端点。generate 默认提交到 `/api/agent/image-requests` 服务端编排入口；`--agent`、`--job`、`--page-sse` 才会显式改用 `/api/agent/images/generate`、`/api/agent/jobs/images/generate` 或页面端 `/api/images` SSE。
 上游探针默认只检查 DNS、TLS 和 `/models`，必须显式添加 `--allow-billable` 才会调用上游 `/images/generations`。
-脚本支持 `GPT_IMAGE_AGENT_CONTRACT_CHECK=1` 或 `--contract-check` 做只读契约检查，会覆盖服务声明的默认编排入口，不触发真实生图或编辑。
+脚本支持 `GPT_IMAGE_AGENT_CONTRACT_CHECK=1` 或 `--contract-check` 做只读契约检查，会覆盖服务声明的默认编排入口和页面 SSE 边界，不触发真实生图或编辑。
 位于仓库根目录且是首次配置、换机器、服务地址不确定或 token 不确定时，先运行 `npm run first-run`。它只读、非计费、不写 env 文件，默认输出中文摘要，并报告 `service_base_url_source`、`interactive_confirmation_required`、服务可达性、当前进程鉴权、页面 SSE 鉴权和下一步动作。
 自动化消费时使用 `npm run first-run -- --json`。
 Agent 端点鉴权以 capabilities 的 `auth.schemes` 为准。配置 `AGENT_API_TOKEN` 时只接受 Bearer token；只有未配置 `AGENT_API_TOKEN` 且配置了 `APP_PASSWORD` 时，Agent 端点才接受访问码哈希 `GPT_IMAGE_APP_PASSWORD_HASH`。页面端 `/api/images` SSE 另看 `agent_streaming.page_sse.auth`；当其声明 `required=true` 时，form-data 必须包含 `passwordHash`。`GPT_IMAGE_AGENT_TOKEN` 不能替代页面 SSE 表单鉴权。

skills/gpt-image-playground-agent/scripts/batch-images.mjs

@@ -173,7 +173,7 @@ try {
   process.exit(2);
 }
 
-const manifestPath = options.manifest || `${options.input}.manifest.jsonl`;
+const manifestPath = resolveManifestPath(options);
 let planned;
 try {
   planned = tasks.map((task, index) => normalizeTask(task, index, options));
@@ -220,6 +220,11 @@ if (!options.allowBillable || options.dryRun) {
   process.exit(0);
 }
 
+if (!manifestPath) {
+  console.error('--input - 真实执行必须显式设置 --manifest，避免无法续跑或审计。');
+  process.exit(2);
+}
+
 try {
   const capacityFeedback = await resolveBatchCapacityFeedback();
   const completed = options.resume ? readCompletedManifestKeys(manifestPath) : new Set();
@@ -275,7 +280,7 @@ function parseArgs(argv) {
     else if (arg === '--resume') parsed.resume = true;
     else if (arg === '--dimension-check') parsed.dimensionCheck = true;
     else if (arg === '--help' || arg === '-h') parsed.help = true;
-    else if (arg === '--input') parsed.input = readOptionValue(argv, (index += 1), arg);
+    else if (arg === '--input') parsed.input = normalizeInputPath(readOptionValue(argv, (index += 1), arg));
     else if (arg === '--manifest') parsed.manifest = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--ordered-prefix') parsed.orderedPrefix = readOptionValue(argv, (index += 1), arg);
     else if (arg === '--timeout-ms') parsed.timeoutMs = readOptionValue(argv, (index += 1), arg);
@@ -286,12 +291,22 @@ function parseArgs(argv) {
     }
     else if (arg === '--concurrency') parsed.concurrency = readOptionValue(argv, (index += 1), arg);
     else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
-    else if (!parsed.input) parsed.input = arg;
+    else if (!parsed.input) parsed.input = normalizeInputPath(arg);
     else throw new Error(`未知位置参数：${arg}`);
   }
   return parsed;
 }
 
+function normalizeInputPath(value) {
+  return value === '-' ? '/dev/stdin' : value;
+}
+
+function resolveManifestPath(parsed) {
+  if (parsed.manifest) return parsed.manifest;
+  if (parsed.input === '/dev/stdin') return null;
+  return `${parsed.input}.manifest.jsonl`;
+}
+
 function buildDryRunVerificationScope() {
   return {
     mode: 'local_planning_only',

skills/gpt-image-playground-agent/scripts/diagnose-request.mjs

@@ -52,6 +52,8 @@ try {
     service_base_url: baseUrl,
     service_base_url_source: baseUrlInfo.source,
     interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
+    page_request_query_count: clientRequestIds.length,
+    page_request_found_count: requests.filter((request) => request.found).length,
     page_request_count: requests.length,
     agent_request_count: agentRequests.length,
     request_count: requests.length,
@@ -62,6 +64,7 @@ try {
   if (requests.length === 1) {
     Object.assign(body, {
       client_request_id: requests[0].client_request_id,
+      found: requests[0].found,
       feedback: requests[0].feedback,
       diagnostics: requests[0].diagnostics,
       ...(requests[0].diagnostics_note ? { diagnostics_note: requests[0].diagnostics_note } : {})
@@ -354,8 +357,10 @@ function readDiagnosticsClientRequestId(value) {
 
 function buildDiagnosedRequest({ clientRequestId, feedback, diagnostics, diagnosticsCapabilities, diagnosticsRetention }) {
   const diagnosticsNote = buildDiagnosticsNoMatchNote(diagnostics, diagnosticsCapabilities, diagnosticsRetention);
+  const found = Boolean(feedback || (diagnostics && diagnostics.matched_log_count > 0));
   return {
     client_request_id: clientRequestId,
+    found,
     feedback,
     diagnostics,
     ...(diagnosticsNote ? { diagnostics_note: diagnosticsNote } : {})

skills/gpt-image-playground-agent/scripts/generate-image.mjs

@@ -134,13 +134,20 @@ try {
 }
 
 if (isNonBillableDryRun(options, contractCheck)) {
+    let remoteCheck;
+    try {
+        remoteCheck = options.checkRemote ? await runRemotePlanningCheck() : buildSkippedRemotePlanningCheck();
+    } catch (error) {
+        console.error(errorMessage(error));
+        process.exit(1);
+    }
     console.log(
         JSON.stringify(
             {
                 ok: true,
                 billable: false,
                 dry_run: true,
-                verification_scope: buildDryRunVerificationScope(),
+                verification_scope: buildDryRunVerificationScope(remoteCheck),
                 endpoint: dryRunEndpoint(requestBody, options.routeMode),
                 route_mode: options.routeMode,
                 routing_guidance: buildGenerateRoutingGuidance(requestBody, options.routeMode),
@@ -256,6 +263,7 @@ function parseArgs(argv) {
         routeMode: 'auto',
         dryRun: false,
         allowBillable: false,
+        checkRemote: false,
         help: false,
         promptParts: []
     };
@@ -289,6 +297,7 @@ function parseArgs(argv) {
         else if (arg === '--base-url') parsed.baseUrl = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--prompt-file') parsed.promptFile = readOptionValue(expandedArgv, (index += 1), arg);
         else if (arg === '--idempotency-key') parsed.idempotencyKey = readOptionValue(expandedArgv, (index += 1), arg);
+        else if (arg === '--check-remote') parsed.checkRemote = true;
         else if (arg.startsWith('--')) throw new Error(`未知参数：${arg}`);
         else parsed.promptParts.push(arg);
     }
@@ -497,20 +506,75 @@ function enrichImageUrls(result) {
     };
 }
 
-function buildDryRunVerificationScope() {
+function buildDryRunVerificationScope(remoteCheck = buildSkippedRemotePlanningCheck()) {
     return {
-        mode: 'local_planning_only',
+        mode: remoteCheck.remote_capabilities_verified ? 'remote_contract_and_local_planning' : 'local_planning_only',
         service_base_url: baseUrl,
         service_base_url_source: baseUrlInfo.source,
         interactive_confirmation_required: baseUrlInfo.interactive_confirmation_required,
+        remote_capabilities_verified: remoteCheck.remote_capabilities_verified,
+        runtime_capacity_verified: remoteCheck.runtime_capacity_verified,
+        auth_verified: remoteCheck.auth_verified,
+        billable_request_sent: false,
+        remote_check: {
+            capabilities: remoteCheck.capabilities,
+            runtime: remoteCheck.runtime
+        },
+        note: remoteCheck.remote_capabilities_verified
+            ? 'Dry-run validated local request construction and read non-billable remote capabilities/runtime state; it did not send a billable image request.'
+            : 'Dry-run validates local request construction and routing guidance only; run --check-remote, --contract-check or --allow-billable to verify the remote service.'
+    };
+}
+
+async function runRemotePlanningCheck() {
+    const capabilities = await readCapabilities();
+    const runtime = await readRuntimeCapabilities();
+    return {
+        remote_capabilities_verified: true,
+        runtime_capacity_verified: true,
+        auth_verified: true,
+        capabilities: {
+            endpoint: AGENT_ENDPOINTS.capabilities,
+            orchestration_supported: capabilities?.orchestration?.supported === true,
+            orchestration_endpoint: capabilities?.orchestration?.endpoint || null,
+            page_sse_supported: capabilities?.agent_streaming?.page_sse?.supported === true,
+            request_modes: readRequestModeList(capabilities?.supported?.request_modes)
+        },
+        runtime: {
+            endpoint: '/api/runtime-capabilities',
+            streaming_batch_enabled: runtime?.streamingBatch?.enabled === true,
+            recommended_concurrency: runtime?.streamingBatch?.recommendedConcurrency ?? null,
+            effective_request_modes: readRequestModeList(runtime?.channelRouting?.effectiveRequestModes)
+        }
+    };
+}
+
+async function readRuntimeCapabilities() {
+    const { response, result, text } = await fetchJson(`${baseUrl}/api/runtime-capabilities`, {
+        headers: authHeaders(),
+        timeoutMs
+    });
+    if (!response.ok) {
+        throw new Error(`runtime-capabilities 请求失败，状态码 ${response.status}：${text}`);
+    }
+    return result;
+}
+
+function buildSkippedRemotePlanningCheck() {
+    return {
         remote_capabilities_verified: false,
         runtime_capacity_verified: false,
         auth_verified: false,
-        billable_request_sent: false,
-        note: 'Dry-run validates local request construction and routing guidance only; run --contract-check or --allow-billable to verify the remote service.'
+        capabilities: null,
+        runtime: null
     };
 }
 
+function readRequestModeList(value) {
+    if (!Array.isArray(value)) return [];
+    return value.filter((item) => typeof item === 'string');
+}
+
 function dryRunEndpoint(body, routeMode) {
     if (routeMode === 'auto' && shouldPreferServerOrchestration(body)) {
         return `${baseUrl}${AGENT_ENDPOINTS.create_image_request}`;
@@ -549,9 +613,11 @@ function buildGenerateRoutingGuidance(body, routeMode) {
             (routeMode !== 'agent' && (hasPageOnlyGenerateOptions(body) || isLargeGenerate(body)))) &&
         isPageSseAllowed(body)
     ) {
-        const reason = hasPageOnlyGenerateOptions(body)
+        const reason = routeMode === 'page_sse'
+            ? 'Explicit --page-sse requests use the page form-data SSE endpoint.'
+            : hasPageOnlyGenerateOptions(body)
             ? 'Responses/GPT2Image-compatible generate options require the page form-data SSE endpoint; Agent JSON generate does not accept those fields.'
-            : 'Generate requests with max_edge>2048 should use page form-data SSE first; if the stream fails, diagnose first and rerun manually with Agent JSON.';
+            : 'Generate requests with page-workbench-only requirements should use the page form-data SSE endpoint; if the stream fails, diagnose first and rerun manually with Agent JSON.';
         return {
             recommended_endpoint: PAGE_SSE_ENDPOINT,
             transport: 'page_sse',
@@ -724,7 +790,7 @@ function assertPageSseReady(capabilitiesValue) {
     if (!supportsPageSse(capabilitiesValue)) {
         throw createScriptError(
             'page_sse_unavailable',
-            '大图默认路由需要 agent_streaming.page_sse.supported=true；capabilities 未声明时不能静默降级到 Agent JSON。'
+            '显式页面 SSE 或页面专属字段需要 agent_streaming.page_sse.supported=true；capabilities 未声明时不能静默降级到 Agent JSON。'
         );
     }
     if (pageSse?.auth?.required === true && !passwordHash) {
@@ -1278,6 +1344,19 @@ async function runContractCheck(capabilitiesValue) {
         checks.push(await checkContractEndpoint(AGENT_ENDPOINTS.create_generate_job));
     }
 
+    if (supportsPageSse(capabilitiesValue)) {
+        const pageSse = capabilitiesValue?.agent_streaming?.page_sse;
+        if (pageSse?.auth?.required === true && !passwordHash) {
+            checks.push({
+                endpoint: PAGE_SSE_ENDPOINT,
+                skipped: true,
+                reason: '页面 SSE 需要 passwordHash；contract-check 在未提供 GPT_IMAGE_APP_PASSWORD_HASH 时跳过。'
+            });
+        } else {
+            checks.push(await checkPageSseContract());
+        }
+    }
+
     console.log(JSON.stringify({ ok: true, billable: false, checks }, null, 2));
 }
 
@@ -1298,6 +1377,35 @@ async function checkContractEndpoint(endpoint) {
     return { endpoint, status: response.status, error_code: result.error.code };
 }
 
+async function checkPageSseContract() {
+    const formData = new FormData();
+    formData.append('mode', 'generate');
+    formData.append('prompt', 'contract check');
+    formData.append('model', requestBody.model);
+    formData.append('n', String(requestBody.n));
+    formData.append('size', requestBody.size);
+    formData.append('quality', requestBody.quality);
+    formData.append('output_format', requestBody.output_format);
+    formData.append('response_mode', requestBody.response_mode);
+    formData.append('stream', 'true');
+    formData.append('clientRequestId', 'x'.repeat(pageSseClientRequestIdMaxLength + 1));
+    if (passwordHash) formData.append('passwordHash', passwordHash);
+    const { response, text } = await fetchJson(`${baseUrl}${PAGE_SSE_ENDPOINT}`, {
+        method: 'POST',
+        body: formData,
+        timeoutMs
+    });
+    if (response.status !== 400 || !text.includes('clientRequestId')) {
+        console.error(JSON.stringify({ ok: false, billable: false, endpoint: PAGE_SSE_ENDPOINT, status: response.status, text }, null, 2));
+        process.exit(1);
+    }
+    return {
+        endpoint: PAGE_SSE_ENDPOINT,
+        status: response.status,
+        error_code: 'page_sse_client_request_id_too_long'
+    };
+}
+
 function readOrchestrationEndpoint(capabilitiesValue) {
     const endpoint = capabilitiesValue?.orchestration?.endpoint;
     if (typeof endpoint !== 'string' || !endpoint.startsWith('/')) {
@@ -1498,7 +1606,7 @@ function printUsage() {
     console.error('用法：generate-image.mjs [options] <prompt>');
     console.error('默认只输出 dry-run；添加 --allow-billable 才会真实生图。');
     console.error(
-        '常用参数：--model --size --quality --n --format --output-compression --response-mode --image-backend --responses-model --gpt-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --sse-log --timeout-ms --base-url --prompt-file --idempotency-key --page-sse --agent --job --no-job(兼容别名)'
+        '常用参数：--model --size --quality --n --format --output-compression --response-mode --image-backend --responses-model --gpt-model --thinking --prompt-optimization --force-web --stream-mode --streaming-strategy --partial-images --sse-log --timeout-ms --base-url --prompt-file --idempotency-key --check-remote --page-sse --agent --job --no-job(兼容别名)'
     );
     console.error(
         '契约检查：GPT_IMAGE_AGENT_CONTRACT_CHECK=1 generate-image.mjs 或 generate-image.mjs --contract-check'

src/app/api/deploy-marker/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 
-const deployMarker = {"schema_version":1,"local_sha":"34544ccd35f4321f92ab73ef5ac36603ee9f7720","created_at":"2026-06-24T14:38:59.964Z","deploy_id":"dee10b1a-4b9c-47bb-a7f3-89875a64183f"} as const;
+const deployMarker = {"schema_version":1,"local_sha":"7af3d19e476e03dfd25eef49672c982b46c64be8","created_at":"2026-06-26T01:06:33.777Z","deploy_id":"46b8343b-982b-4f3b-8526-ca1feabfd227"} as const;
 
 export const dynamic = 'force-dynamic';
 

src/lib/agent-api-contracts.test.ts

@@ -439,7 +439,7 @@ describe('buildAgentCapabilities', () => {
         });
         assert.equal(
             capabilities.agent_streaming.page_sse.agent_usage,
-            'explicit_for_generate_recommended_for_high_resolution_edit_and_complex_batch'
+            'explicit_for_generate_recommended_for_page_only_fields_high_resolution_edit_and_complex_batch'
         );
         assert.deepEqual(capabilities.upstream_request_headers.default, {
             user_agent_effective: 'gpt-image-playground/2.1.0',

src/lib/agent-api-contracts.ts

@@ -334,7 +334,7 @@ export type AgentCapabilities = {
                 source_header: 'Idempotency-Key';
                 max_length: number;
             };
-            agent_usage: 'explicit_for_generate_recommended_for_high_resolution_edit_and_complex_batch';
+            agent_usage: 'explicit_for_generate_recommended_for_page_only_fields_high_resolution_edit_and_complex_batch';
         };
     };
     orchestration: {
@@ -1013,7 +1013,7 @@ export function buildAgentCapabilities(env: Record<string, string | undefined>):
                     source_header: 'Idempotency-Key',
                     max_length: PAGE_SSE_CLIENT_REQUEST_ID_MAX_LENGTH
                 },
-                agent_usage: 'explicit_for_generate_recommended_for_high_resolution_edit_and_complex_batch'
+                agent_usage: 'explicit_for_generate_recommended_for_page_only_fields_high_resolution_edit_and_complex_batch'
             }
         },
         orchestration: {
@@ -1050,7 +1050,7 @@ export function buildAgentCapabilities(env: Record<string, string | undefined>):
                     requires_new_idempotency_key_on_retry: true,
                     no_automatic_fallback: true
                 },
-                reason: 'High-resolution edit defaults to the page form-data SSE endpoint; if streaming has issues, diagnose first and explicitly fall back to Agent edit.'
+                reason: 'High-resolution edit uses the page form-data SSE endpoint because Agent edit has a fixed output contract; if streaming has issues, diagnose first and explicitly fall back to Agent edit.'
             },
             complex_ui_batch: {
                 when: ['operation=generate_or_edit', 'complex_ui=true', 'batch=true'],