astra-preflight

Astra Preflight

Catch GPT-6 Astra request incompatibilities before calling the API.

Try the playground → · Rule coverage · 한국어

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

npx astra-preflight request.json

Or open the example without installing anything.

Given this request:

{
  "model": "gpt-6-astra",
  "input": "Summarize the release notes.",
  "temperature": 0.7,
  "reasoning": { "effort": "none" }
}

The CLI reports:

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.

# 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

npm install astra-preflight

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, QM #951: tool-enabled Astra requests fail on Chat Completions	--api chat diagnoses tool workflow incompatibility
Bifrost #6880: requested max becomes high	--expect-effort max checks an outgoing payload
TeXRA #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

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 or a documented rule with positive and negative tests. See 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.