astra-preflight 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JinHyuk Sung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+<a href="https://sjh9714.github.io/astra-preflight/"><img src="https://sjh9714.github.io/astra-preflight/social.png" alt="Astra Preflight. Your model changed. Did your payload? An offline GPT-6 Astra migration checker." width="100%"></a>
+
+# Astra Preflight
+
+**Catch GPT-6 Astra request incompatibilities before calling the API.**
+
+[![CI](https://github.com/sjh9714/astra-preflight/actions/workflows/ci.yml/badge.svg)](https://github.com/sjh9714/astra-preflight/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/astra-preflight.svg)](https://www.npmjs.com/package/astra-preflight)
+[![MIT](https://img.shields.io/badge/license-MIT-316a4c.svg)](LICENSE)
+
+[**Try the playground →**](https://sjh9714.github.io/astra-preflight/) · [Rule coverage](docs/rules.md) · [한국어](docs/README.ko.md)
+
+Switching the model name can leave behind incompatible settings. Astra Preflight checks a **request JSON payload** locally, links findings to official documentation, and offers a reviewable draft.
+
+- **No API key, server, telemetry, or runtime dependencies.** Node.js 20+ for the CLI; a browser for the playground.
+- Check sampling parameters, reasoning effort, tool endpoints, cache settings, EU Fast mode, and token limits.
+- Catch gateway effort changes with `--expect-effort max` against the **final outgoing payload**.
+- Keep your source unchanged. `--draft` prints a copy; endpoint and tool-conversation migrations stay manual.
+
+## Try it in 30 seconds
+
+```sh
+npx astra-preflight request.json
+```
+
+Or [open the example](https://sjh9714.github.io/astra-preflight/?example=legacy) without installing anything.
+
+Given this request:
+
+```json
+{
+  "model": "gpt-6-astra",
+  "input": "Summarize the release notes.",
+  "temperature": 0.7,
+  "reasoning": { "effort": "none" }
+}
+```
+
+The CLI reports:
+
+```text
+Astra Preflight  BLOCKED
+2 errors · 0 warnings · rules 2026-09-05
+
+ERROR AP002  /temperature  Unsupported sampling parameter
+ERROR AP003  /reasoning/effort  Unsupported reasoning effort
+```
+
+Output above is abbreviated; the actual report includes explanations and official source links.
+
+```sh
+# Print a draft to stdout for review; do not redirect over your input file.
+npx astra-preflight request.json --draft
+
+# Check a Chat Completions payload (text-only Astra calls are supported).
+npx astra-preflight request.json --api chat
+
+# Migrate a payload that still names a different model.
+npx astra-preflight request.json --target
+
+# A gateway may silently rewrite max to high. Inspect what it actually sends.
+npx astra-preflight outgoing.json --expect-effort max
+
+# The 272K threshold counts total input, including cached tokens.
+npx astra-preflight request.json --input-tokens 272001 --strict
+
+# JSON diagnostics for CI. Your prompt and payload are omitted.
+npx astra-preflight request.json --format json
+```
+
+Use `-` to read stdin. `--region eu` enables the EU Fast mode check. `--format md` emits Markdown. Full options: `npx astra-preflight --help`.
+
+Exit codes: **0** no blocking documented finding; **1** errors (or warnings with `--strict`); **2** invalid input, invalid usage, or an unassessed model. A clear report is not a complete API validation.
+
+## Use in code
+
+```sh
+npm install astra-preflight
+```
+
+```js
+import { inspectRequest } from 'astra-preflight';
+
+const request = {
+  model: 'gpt-6-astra',
+  input: 'Summarize the release notes.',
+  reasoning: { effort: 'max' }
+};
+
+const report = inspectRequest(request, { expectedEffort: 'max' });
+if (!report.assessed || report.errors) {
+  throw new Error('Review the preflight diagnostics before sending.');
+}
+// Send request through your existing SDK here.
+```
+
+`inspectRequest` and `draftRequest` are pure functions with TypeScript declarations. They do not contact OpenAI or inspect your SDK's internals. Check **after** transformations to detect gateway changes; checking only the original caller input cannot detect a later rewrite.
+
+## Why these checks?
+
+These are motivated by launch-period integration reports, not an invented benchmark:
+
+| Reported problem | What you can check |
+| --- | --- |
+| [Docker Agent #4162](https://github.com/docker/docker-agent/issues/4162), [QM #951](https://github.com/yc-software/qm/issues/951): tool-enabled Astra requests fail on Chat Completions | `--api chat` diagnoses tool workflow incompatibility |
+| [Bifrost #6880](https://github.com/maximhq/bifrost/issues/6880): requested `max` becomes `high` | `--expect-effort max` checks an outgoing payload |
+| [TeXRA #11878](https://github.com/LionSR/TeXRA/issues/11878): long-context accounting and saved `minimal` effort | Supplied-token threshold and effort checks |
+
+The examples are **synthetic reproductions of the reported payload patterns**, not live tests of those projects. Issue status can change. Technical rules come from linked official OpenAI documentation, checked on **September 5, 2026**.
+
+## Scope and privacy
+
+This release checks individual JSON requests for 14 rule families. It does **not** scan repositories, tokenize input, validate every API field, execute tools, monitor WebSocket steering, check billing, or verify model access. These are API checks; they do not calculate Codex subscription credits. A successful report is not a runtime guarantee.
+
+The playground runs locally after loading its static files. It does not store or upload entered JSON. The CLI reports contain fixed diagnostics and JSON pointers, not prompts or keys. **`--draft` and “Copy draft” intentionally output a copy of your payload**; keep that copy private.
+
+## Development
+
+```sh
+git clone https://github.com/sjh9714/astra-preflight.git
+cd astra-preflight
+npm test
+npm run check
+npm run build
+npm run dev
+# http://127.0.0.1:4173
+```
+
+There is nothing to install for development: tests use Node's built-in runner, and the static build copies the shared checker. Tests cover request boundaries, draft preservation, gateway drift, and CLI exit/privacy behavior. No live OpenAI API tests are included.
+
+Contribute a [redacted reproduction](https://github.com/sjh9714/astra-preflight/issues/new?template=bug_report.yml) or a documented rule with positive and negative tests. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+If this saves you a debugging session, a GitHub star helps other Astra developers find it.
+
+MIT · Independent community project; not affiliated with OpenAI.

package/bin/cli.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { inspectRequest, draftRequest, RULESET_DATE } from '../src/preflight.mjs';
+
+const HELP = `Astra Preflight — offline GPT-6 Astra request checks
+
+Usage: astra-preflight <request.json | -> [options]
+
+  --api responses|chat       Request endpoint (default: responses)
+  --region global|eu         Your API data residency (default: global)
+  --target                  Assess a different model's payload for Astra
+  --input-tokens N           Explicit total input count; enables limit/pricing checks
+  --expect-effort EFFORT     Detect missing or changed reasoning effort
+  --format text|json|md      Diagnostics format (default: text)
+  --draft                   Print a reviewable JSON payload to stdout
+  --strict                  Exit 1 on warnings as well as errors
+  --help                    Show this help
+  --version                 Show version and ruleset date
+
+Exit codes: 0 = no blocking documented finding; 1 = findings; 2 = invalid input,
+usage, or a request that was not assessed. No API calls or telemetry.
+Diagnostics omit your payload. --draft intentionally prints a copy of it;
+keep that output private. Existing files are never modified by the CLI.
+`;
+
+async function readStdin() {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > 2 * 1024 * 1024) throw new Error('Input exceeds the 2 MiB limit.');
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function render(report, format) {
+  if (format === 'json') return JSON.stringify(report, null, 2);
+  if (format === 'md') return [
+    `## Astra Preflight: ${report.status}`,
+    '', `${report.errors} errors · ${report.warnings} warnings · Rules checked ${report.ruleset}`, '',
+    ...report.diagnostics.flatMap(d => [
+      `- **${d.id} ${d.severity}: ${d.title}** — \`${d.path}\``,
+      `  ${d.detail} [Official source](${d.source})`,
+    ]), '', report.coverage,
+  ].join('\n');
+  return [
+    `Astra Preflight  ${report.status.toUpperCase()}`,
+    `${report.errors} errors · ${report.warnings} warnings · rules ${report.ruleset}`, '',
+    ...report.diagnostics.flatMap(d => [
+      `${d.severity.toUpperCase()} ${d.id}  ${d.path}  ${d.title}`,
+      `  ${d.detail}`, `  ${d.source}`, '',
+    ]), report.coverage,
+  ].join('\n');
+}
+
+async function main(args) {
+  if (args.includes('--help') || args.includes('-h')) return void console.log(HELP);
+  if (args.includes('--version')) return void console.log(`0.1.0 (rules ${RULESET_DATE})`);
+  const options = {};
+  let file, format = 'text', draft = false, strict = false;
+  const valueFlags = { '--api': 'api', '--region': 'region', '--input-tokens': 'inputTokens', '--expect-effort': 'expectedEffort' };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--target') options.target = true;
+    else if (arg === '--draft') draft = true;
+    else if (arg === '--strict') strict = true;
+    else if (arg === '--format' || Object.hasOwn(valueFlags, arg)) {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--')) throw new Error('An option is missing its value. Use --help.');
+      if (arg === '--format') format = value;
+      else if (arg === '--input-tokens') {
+        if (!/^\d+$/.test(value)) throw new Error('Input tokens must be a nonnegative integer.');
+        options.inputTokens = Number(value);
+      } else options[valueFlags[arg]] = value;
+    } else if (arg.startsWith('-') && arg !== '-') throw new Error('Unknown option. Use --help.');
+    else if (file !== undefined) throw new Error('Provide exactly one request file, or - for stdin.');
+    else file = arg;
+  }
+  if (!file) throw new Error('Provide a request JSON file, or - for stdin. Use --help.');
+  if (!['text', 'json', 'md'].includes(format)) throw new Error('Format must be text, json, or md.');
+  if (draft && format !== 'text') throw new Error('--draft already emits JSON; do not combine it with --format.');
+  let content;
+  try { content = file === '-' ? await readStdin() : await readFile(file, 'utf8'); }
+  catch { throw new Error('Could not read input. Check the file path or stdin size.'); }
+  if (Buffer.byteLength(content) > 2 * 1024 * 1024) throw new Error('Input exceeds the 2 MiB limit.');
+  let request;
+  try { request = JSON.parse(content); }
+  catch { throw new Error('Input is not valid JSON. Parse details are omitted to keep payload content private.'); }
+  let report;
+  if (draft) {
+    const result = draftRequest(request, options);
+    report = result.report;
+    console.log(JSON.stringify(result.request, null, 2));
+    console.error(`Review draft: ${result.changes.length} edits; ${report.errors} errors, ${report.warnings} warnings remain. Original input unchanged.`);
+  } else {
+    report = inspectRequest(request, options);
+    console.log(render(report, format));
+  }
+  process.exitCode = !report.assessed ? 2 : (report.errors || (strict && report.warnings)) ? 1 : 0;
+}
+
+main(process.argv.slice(2)).catch(error => {
+  console.error(`Astra Preflight: ${error.message}`);
+  process.exitCode = 2;
+});

package/examples/chat-tools.json

@@ -0,0 +1,10 @@
+{
+  "model": "gpt-6-astra",
+  "messages": [{ "role": "user", "content": "Check the build status." }],
+  "reasoning_effort": "medium",
+  "tools": [{ "type": "function", "function": {
+    "name": "get_build_status",
+    "description": "Read the current build status.",
+    "parameters": { "type": "object", "properties": {}, "additionalProperties": false }
+  } }]
+}

package/examples/legacy-responses.json

@@ -0,0 +1,9 @@
+{
+  "model": "gpt-6-astra",
+  "input": "Summarize the release notes in three bullets.",
+  "temperature": 0.7,
+  "top_p": 0.9,
+  "reasoning": { "effort": "none" },
+  "prompt_cache_retention": "24h",
+  "max_output_tokens": 2000
+}

package/examples/ready.json

@@ -0,0 +1,7 @@
+{
+  "model": "gpt-6-astra",
+  "input": "Summarize the release notes in three bullets.",
+  "reasoning": { "effort": "low" },
+  "prompt_cache_options": { "ttl": "30m" },
+  "max_output_tokens": 2000
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "astra-preflight",
+  "version": "0.1.0",
+  "description": "Catch GPT-6 Astra request incompatibilities before calling the API. Offline CLI, JavaScript library, and browser playground.",
+  "type": "module",
+  "license": "MIT",
+  "author": "JinHyuk Sung",
+  "repository": { "type": "git", "url": "git+https://github.com/sjh9714/astra-preflight.git" },
+  "homepage": "https://sjh9714.github.io/astra-preflight/",
+  "bugs": { "url": "https://github.com/sjh9714/astra-preflight/issues" },
+  "keywords": ["gpt-6", "astra", "openai", "migration", "responses-api", "validator", "cli"],
+  "engines": { "node": ">=20" },
+  "bin": { "astra-preflight": "bin/cli.mjs" },
+  "exports": { ".": { "types": "./src/index.d.ts", "import": "./src/preflight.mjs", "default": "./src/preflight.mjs" } },
+  "files": ["bin/", "src/", "examples/", "LICENSE", "README.md"],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/preflight.mjs && node --check bin/cli.mjs && node --check site/app.mjs",
+    "build": "node scripts/build.mjs",
+    "dev": "node scripts/serve.mjs",
+    "prepublishOnly": "npm test && npm run check"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,37 @@
+export const MODEL: 'gpt-6-astra';
+export const RULESET_DATE: string;
+export const SOURCES: Readonly<Record<string, string>>;
+export interface Options {
+  api?: 'responses' | 'chat';
+  region?: 'global' | 'eu';
+  target?: boolean;
+  inputTokens?: number;
+  expectedEffort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+}
+export interface Diagnostic {
+  id: string;
+  severity: 'error' | 'warning' | 'info';
+  path: string;
+  title: string;
+  detail: string;
+  source: string;
+  edit?: { op: 'remove' | 'replace' | 'add'; path: string; value?: unknown };
+}
+export interface Report {
+  ruleset: string;
+  api: 'responses' | 'chat';
+  region: 'global' | 'eu';
+  targetModel: string;
+  assessed: boolean;
+  status: 'blocked' | 'review' | 'clear' | 'not-applicable';
+  errors: number;
+  warnings: number;
+  diagnostics: Diagnostic[];
+  coverage: string;
+}
+export function inspectRequest(request: Record<string, unknown>, options?: Options): Report;
+export function draftRequest(request: Record<string, unknown>, options?: Options): {
+  request: Record<string, unknown>;
+  changes: { id: string; path: string }[];
+  report: Report;
+};

package/src/preflight.mjs

@@ -0,0 +1,154 @@
+/** Offline rules for documented GPT-6 Astra request incompatibilities. */
+export const MODEL = 'gpt-6-astra';
+export const RULESET_DATE = '2026-09-05';
+export const SOURCES = Object.freeze({
+  migration: 'https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra',
+  responses: 'https://developers.openai.com/api/docs/guides/migrate-to-responses',
+  model: 'https://developers.openai.com/api/docs/models/gpt-6-astra',
+  reasoning: 'https://developers.openai.com/api/docs/guides/reasoning',
+  caching: 'https://developers.openai.com/api/docs/guides/prompt-caching',
+  async: 'https://developers.openai.com/api/docs/guides/async-tool-calling',
+  fast: 'https://developers.openai.com/api/docs/guides/fast-mode',
+});
+const efforts = ['low', 'medium', 'high', 'xhigh', 'max'];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const has = (value, key) => Object.hasOwn(value, key);
+
+export function inspectRequest(request, options = {}) {
+  if (!object(request)) throw new TypeError('Request must be a JSON object.');
+  const { api = 'responses', region = 'global', target = false, inputTokens, expectedEffort } = options;
+  if (!['responses', 'chat'].includes(api)) throw new TypeError('API must be responses or chat.');
+  if (typeof target !== 'boolean') throw new TypeError('Migration target must be a boolean.');
+  if (!['global', 'eu'].includes(region)) throw new TypeError('Region must be global or eu.');
+  if (inputTokens !== undefined && (!Number.isSafeInteger(inputTokens) || inputTokens < 0)) {
+    throw new TypeError('Input tokens must be a nonnegative safe integer.');
+  }
+  if (expectedEffort !== undefined && !efforts.includes(expectedEffort)) {
+    throw new TypeError('Expected effort must be low, medium, high, xhigh, or max.');
+  }
+  const diagnostics = [];
+  const add = (id, severity, path, title, detail, source = 'migration', edit) => {
+    diagnostics.push({ id, severity, path, title, detail, source: SOURCES[source], ...(edit ? { edit } : {}) });
+  };
+  const result = () => ({
+    ruleset: RULESET_DATE, api, region, targetModel: MODEL, assessed: target || request.model === MODEL,
+    status: diagnostics.some(d => d.severity === 'error') ? 'blocked'
+      : !(target || request.model === MODEL) ? 'not-applicable'
+      : diagnostics.some(d => d.severity === 'warning') ? 'review' : 'clear',
+    errors: diagnostics.filter(d => d.severity === 'error').length,
+    warnings: diagnostics.filter(d => d.severity === 'warning').length,
+    diagnostics,
+    coverage: 'Documented request checks only. No API call, account-access check, full schema validation, or runtime guarantee.',
+  });
+  if (!target && request.model !== MODEL) {
+    add('AP001', 'warning', '/model', 'Astra request required',
+      'Set model to gpt-6-astra, or explicitly enable migration preview to assess this payload for Astra.', 'model');
+    return result();
+  }
+  if (target && request.model !== MODEL) {
+    add('AP001', 'info', '/model', 'Migration preview targets Astra',
+      'The draft will use gpt-6-astra. Evaluate output quality and account access separately.', 'model',
+      { op: has(request, 'model') ? 'replace' : 'add', path: '/model', value: MODEL });
+  }
+  for (const key of ['temperature', 'top_p', 'top_logprobs', ...(api === 'chat' ? ['logprobs'] : [])]) {
+    if (has(request, key)) add('AP002', request[key] === null ? 'warning' : 'error', `/${key}`,
+      'Unsupported sampling parameter', `Remove ${key} from the request. Express style preferences in instructions.`,
+      'migration', { op: 'remove', path: `/${key}` });
+  }
+  const effortPath = api === 'responses' ? '/reasoning/effort' : '/reasoning_effort';
+  const effort = api === 'responses' ? request.reasoning?.effort : request.reasoning_effort;
+  if (effort !== undefined && !efforts.includes(effort)) {
+    add('AP003', 'error', effortPath, 'Unsupported reasoning effort',
+      'Astra supports low, medium, high, xhigh, and max. Review low as a starting point when migrating none or minimal.', 'reasoning',
+      ['none', 'minimal'].includes(effort) ? { op: 'replace', path: effortPath, value: 'low' } : undefined);
+  }
+  if (expectedEffort !== undefined && effort !== expectedEffort) {
+    add('AP004', 'error', effortPath, 'Reasoning differs from your expectation',
+      'The explicit effort in this payload does not match --expect-effort. Inspect the final serialized request after gateway or SDK transformations.', 'reasoning');
+  }
+  if (api === 'chat' && ((Array.isArray(request.tools) && request.tools.length > 0)
+    || has(request, 'functions') || has(request, 'function_call') || has(request, 'tool_choice'))) {
+    add('AP005', 'error', '/tools', 'Astra tool calling needs Responses',
+      'Move this tool workflow to /v1/responses and translate messages, tool definitions, and tool results. Changing the URL alone is insufficient. This step requires review.');
+  }
+  if (Array.isArray(request.include) && request.include.includes('message.output_text.logprobs')) {
+    add('AP006', 'error', '/include', 'Log probabilities are unavailable',
+      'Remove message.output_text.logprobs from include.', 'migration');
+  }
+  if (has(request, 'prompt_cache_retention')) {
+    add('AP007', 'error', '/prompt_cache_retention', 'Legacy cache retention field',
+      'Replace prompt_cache_retention with prompt_cache_options.ttl set to 30m. Review the different retention and cache-write billing.', 'caching');
+  }
+  if (object(request.prompt_cache_options) && has(request.prompt_cache_options, 'ttl') && request.prompt_cache_options.ttl !== '30m') {
+    add('AP008', 'error', '/prompt_cache_options/ttl', 'Unsupported cache lifetime',
+      'The documented cache lifetime option for Astra is 30m.', 'caching',
+      { op: 'replace', path: '/prompt_cache_options/ttl', value: '30m' });
+  }
+  if (region === 'eu' && ['fast', 'priority'].includes(request.service_tier)) {
+    add('AP009', 'error', '/service_tier', 'Fast mode is unavailable with EU residency',
+      'Use standard processing for Astra with EU data residency. Verify your organization and endpoint configuration.', 'fast',
+      { op: 'remove', path: '/service_tier' });
+  }
+  const wrongFields = api === 'responses' ? ['messages', 'reasoning_effort', 'max_completion_tokens', 'max_tokens', 'response_format', 'n']
+    : ['input', 'reasoning', 'max_output_tokens', 'previous_response_id', 'text'];
+  for (const field of wrongFields) {
+    if (has(request, field)) add('AP010', 'error', `/${field}`, 'Field belongs to a different API shape',
+      `Review ${field} for the selected ${api === 'chat' ? 'Chat Completions' : 'Responses'} endpoint. Payload and tool-result formats differ; this tool does not convert conversations.`, 'responses');
+  }
+  const limitKey = api === 'responses' ? 'max_output_tokens' : 'max_completion_tokens';
+  if (has(request, limitKey) && (!Number.isSafeInteger(request[limitKey]) || request[limitKey] < 1 || request[limitKey] > 128000)) {
+    add('AP011', 'error', `/${limitKey}`, 'Output budget is outside the model limit',
+      'Use an integer output budget within the documented 128,000-token maximum. Endpoint-specific minimums are not checked.', 'model');
+  }
+  if (Array.isArray(request.tools)) request.tools.forEach((tool, index) => {
+    if (!object(tool)) return;
+    if (tool.async === true && !['function', 'custom'].includes(tool.type)) {
+      add('AP012', 'error', `/tools/${index}/async`, 'Async applies to client function or custom tools',
+        'Hosted built-in tools cannot be marked async. Your application owns execution and pending results for client tools.', 'async');
+    }
+    if (tool.type === 'function' && api === 'responses' && object(tool.function)) {
+      add('AP013', 'error', `/tools/${index}/function`, 'Chat-style function wrapper',
+        'Responses function tools put name, description, and parameters directly on the tool object. Review strict schemas and your result handling before migration.', 'responses');
+    }
+  });
+  if (inputTokens !== undefined) {
+    if (inputTokens > 922000) add('AP014', 'error', '/input', 'Input exceeds the documented maximum',
+      'Astra accepts at most 922,000 input tokens. This check uses your supplied count, not a tokenizer.', 'model');
+    else if (inputTokens > 272000) add('AP014', 'warning', '/input', 'Long-context pricing applies to the whole request',
+      'Above 272,000 input tokens, input and cache rates double and output rates rise by 1.5× for the full request. This is API pricing, not Codex subscription usage.', 'model');
+    if (inputTokens + (Number.isSafeInteger(request[limitKey]) ? request[limitKey] : 0) > 1050000) {
+      add('AP014', 'error', `/${limitKey}`, 'Input and output budget exceed the context window',
+        'The documented context window is 1,050,000 tokens. Reduce the supplied input count or requested output budget.', 'model');
+    }
+  }
+  return result();
+}
+
+/** Produces a reviewable copy. Never writes files or converts tool conversations. */
+export function draftRequest(request, options = {}) {
+  const report = inspectRequest(request, options);
+  const draft = JSON.parse(JSON.stringify(request));
+  const changes = [];
+  for (const diagnostic of report.diagnostics) {
+    const edit = diagnostic.edit;
+    if (!edit) continue;
+    const keys = edit.path.slice(1).split('/');
+    let parent = draft;
+    for (const key of keys.slice(0, -1)) parent = parent[key];
+    const key = keys.at(-1);
+    if (edit.op === 'remove') delete parent[key];
+    else parent[key] = edit.value;
+    changes.push({ id: diagnostic.id, path: edit.path });
+  }
+  if (report.assessed && has(draft, 'prompt_cache_retention') &&
+    (!has(draft, 'prompt_cache_options') || object(draft.prompt_cache_options))) {
+    delete draft.prompt_cache_retention;
+    draft.prompt_cache_options = { ...draft.prompt_cache_options, ttl: '30m' };
+    changes.push({ id: 'AP007', path: '/prompt_cache_options/ttl' });
+  }
+  if (report.assessed && Array.isArray(draft.include) && draft.include.includes('message.output_text.logprobs')) {
+    draft.include = draft.include.filter(value => value !== 'message.output_text.logprobs');
+    changes.push({ id: 'AP006', path: '/include' });
+  }
+  return { request: draft, changes, report: inspectRequest(draft, options) };
+}