AGENTS.md · openai/openai-node

Sections

1. Generated SDK
2. Start with the actual problem
3. Keep changes small and coherent
4. Preserve SDK contracts and compatibility
5. Custom-code budget
6. Security and lifecycle correctness
7. Tooling, dependencies, and verification
8. Node.js version policy

First lines (shown under the repo's Apache-2.0 license)

# Repository Guidance

## Generated SDK

Most SDK source is generated from the OpenAI API schema. Follow `.github/CONTRIBUTING.md` before
changing generated files. Handwritten policy, automation, tests, and examples
should remain small and should not alter exported SDK APIs unless the change
explicitly requires it.

## Start with the actual problem

- For externally observable bug or behavior fixes, reproduce the reported issue
  against the current repository and public SDK entrypoint before proposing a fix.
  Check existing issues and pull requests; inspect the API schema and
  generated/upstream ownership only when relevant. Do not duplicate existing work,
  "fix" intended API behavior, or patch a generated symptom that belongs in the
  schema or generator.
- For those behavior fixes, include a focused regression that fails before the change
  and passes afterward. Type errors need a compile-time reproduction; stream, transport,
  and packaging bugs need coverage at the actual affected boundary, not merely a
  passing internal mock.
- For docs-only, dependency-only, generated, formatting, workflow, or policy changes
  without an observable bug, use the smallest artifact-appropriate validation, such
  as link, render, configuration, installation, or build checks.

## Keep changes small and coherent

- Solve the narrow problem with the simplest implementation. Avoid unrelated
  refactors, reformatting, dependency or lockfile churn, generated-file edits,
  speculative abstractions, compatibility shims, and capabilities not requested.
- Establish an invariant once at its owning boundary instead of compensating in
  every caller. Reuse existing parsers, registries, helpers, and compiler/runtime
  facilities instead of creating parallel infrastructure or a hand-written parser.
  If successive edge cases keep appearing, reconsider the invariant and ownership
  rather than adding another special case.
- Model incomplete API/SSE wire shapes separately from enriched public SDK types.
  Keep required public snapshot fields accurate before exposing them, or type
  fields unavailable until later truthfully. Normalize incomplete items at their
  owning boundary instead of patching downstream consumers. Prefer TypeScript
  narrowing and inference over broad `any`, assertions, `@ts-ignore`, or casts
  that disguise an unproven contract.
- Keep handwritten production and test files cohesive. Extract a well-defined owner
  only when the current change materially grows a file and reveals a coherent,
  distinct responsibility. Keep unrelated cleanup separate, and do not inflate
  fixtures or suites to justify an overly complicated implementation.
- Avoid hand-maintained model, endpoint, capability, or schema lists unless the
  contract requires them. Prefer the documented API/schema and server-side
  validation over brittle client-side guesses.

## Preserve SDK contracts and compatibility

- Compare behavior with the base revision across existing public exports and import
  subpaths, provider and legacy clients, stable and beta surfaces, and equivalent
  streaming/non-streaming paths. Preserve published TypeScript declarations,
  overloads, optional fields, discriminators, object identity, protected hooks,
  request-option/header precedence, client cloning, and documented defaults unless
  the task explicitly authorizes a breaking change.
- Preserve meaningful `0`, `false`, and empty-string values, and distinguish
  explicit `null` from an omitted or `undefined` value where the contract does.
  Do not replace presence or nullish checks with truthiness checks.
- For schema helpers, check supported Zod v3/v4 and Standard Schema integrations,
  inferred output types, escaped JSON Pointer references, and the actual serialized
  schema rather than trusting an idealized intermediate TypeScript shape.
- Verify affected CJS/ESM entrypoints, the exact minimum supported Node version,
  affected policy-defined Node lines, supported TypeScript versions, and relevant
  browser, worker, Bun, Deno, bundler, or serverless integrations. The newest CI
  version passing does not prove compatibility with the minimum supported version.
- Keep optional integrations isolated from the core SDK. Do not make a provider's
  optional dependency, environment, credential, or runtime requirement mandatory
  for unrelated clients; test both installed and absent optional dependencies when
  the import boundary changes.
- Update affected canonical docs, executable examples, or meaningful public JSDoc
  when the public contract changes. Preserve existing documentation URLs and import
  paths, and make examples runnable with the documented environment and dependencies.

## Generated-file ownership

Never hand-edit generated SDK files, including generated tests, documentation,
workflows, or the generated-file inventory. Change the authoritative API schema,
configuration, or compiler, then regenerate. Put SDK-specific behavior in
separately owned handwritten helpers and extension points.

Regeneration replaces generator-owned files and deletes retired generated paths.
Handwritten edits to generated files are overwritten; they are never replayed or
merged into new output. Preserve separately owned handwritten files and resolve
ownership collisions explicitly. Follow this AGENTS.md rule and review generated output and inventory changes
together. Generated-file ownership currently relies on contributor guidance and
code review; there is no dedicated generated-file edit check or required gate.
Fix violations in the inputs/compiler and regenerate; never update inventory
hashes to accept a handwritten patch.

## Security and lifecycle correctness

- Never commit API keys, tokens, private keys, `.env` files, customer data, or other
  secrets. Read `OPENAI_API_KEY` from the environment and keep examples, fixtures,
  recordings, and snapshots synthetic.
- Never place secret API keys in browser bundles or enable `dangerouslyAllowBrowser`
  without explicit security review. Always redact credentials, authorization
  headers, cookies, and webhook secrets. Keep real customer-sensitive request or
  response data out of default or uncontrolled logs, errors, test output,
  snapshots, and CI artifacts. Preserve documented opt-in `OPENAI_LOG=debug`
  or `logLevel: 'debug'` logging and `APIError.error` diagnostics with clear
  sensitive-data warnings; redact them before forwarding to untrusted sinks.
- Treat provider endpoints, headers, filenames, schemas, and object properties as
  untrusted. At JSON object-record boundaries, validate the own properties and
  values actually emitted, accounting for serialization hooks and omitted values;
  reject or safely preserve dangerous prototype keys. Preserve supported inherited
  protocols and validate the final request, including normalized host/origin,
  redirects, protected hooks, custom fetch transports, and both current and legacy
  entrypoints. Never leak bearer tokens, API keys, certificates, request bodies,
  or other credentials across trust boundaries.
- When validation and dispatch must agree, snapshot only the security-critical
  values or serialized representation, within bounded memory, before irreversible
  network or request-body side effects. Preserve request-options object identity
  and protected-hook mutations; never validate one mutable representation and
  serialize another.
- Keep workflow tokens, permissions, and secrets at the narrowest required scope.
  Bind privileged checkout, release, and publication operations to the validated,
  immutable commit; do not trust floating refs, mutable tags, optional checks, or
  assumptions about repository settings and app permissions.
- Pin third-party GitHub Actions to full, immutable commit SHAs. Publish npm packages
  only through protected GitHub Actions OIDC trusted publishing; never add token-based
  release paths. Expose GitHub App private keys, OIDC credentials, and permissions only to
  trusted release jobs; never expose them to unreviewed scripts or untrusted code.
- For streaming, uploads, authentication, retries, timeouts, and cancellation,
  exercise the complete request/response lifetime: headers, JSON/error/binary/SSE
  bodies, raw responses, async iterators, redirect handling, abort reasons, retry
  budgets, concurrent refresh, cleanup, and reader/listener/lock ownership as
  applicable. Avoid new retained state and accidental quadratic hot paths.
- Treat large payloads as a normal API contract, not evidence of malformed or
  hostile input. Responses, Chat Completions, and other APIs can legitimately
  return large `application/json` bodies, streaming events, and WebSocket
  messages. Do not introduce arbitrary fixed limits on bodies, frames, events,
  or lines as a security or efficiency fix. Prefer incremental processing,
  amortized-linear buffering, timely cleanup, and caller cancellation. Any new
  rejection limit needs an explicit, owner-approved API contract and a review
  of existing supported payloads and transports. Protect this behavior with
  deterministic public-entrypoint tests that construct large synthetic payloads
  in memory; do not commit large captures or require slow live image generation.
- Give every cache an explicit owner, complete identity key, lifetime, and
  invalidation policy. Do not trust caller-mutable snapshots, conflate changed
  transport/certificate identities, or leak request/client-specific state or
  credentials across clients, transports, retries, or authentication contexts.
- Require focused security review and relevant regression tests for authentication,
  network destinations or headers, browser credentials, files and uploads, webhook
  signatures, parsing, serialization, dependencies, and release automation. Report
  suspected vulnerabilities privately via `.github/SECURITY.md`; never disclose
  them in public issues or pull requests.

## Tooling, dependencies, and verification

- Follow `.github/CONTRIBUTING.md` and the tool versions pinned by `.nvmrc` and
  `package.json`. Keep `./scripts/test`, `./scripts/lint`, and `./scripts/format`
  as the canonical script entrypoints, with package-manager aliases and CI routing
  through them; preserve both generated and handwritten suite coverage.
- For dependency changes, update only the requested package and its dependency
  closure. Check `pnpm install --frozen-lockfile`, module format, supported runtime
  and TypeScript floors, minimum-release-age/trust policy, and audited lifecycle
  build permissions; do not hide unrelated transitive upgrades in the lockfile.
- Make changed files pass the actual pinned formatter and linter. Do not disguise