summary: "Overview and quickstart for monorepo package @tryinget/pi-better-openai." read_when:

• "Starting work in this package workspace." system4d: container: "Monorepo package scaffold for pi extension delivery." compass: "Ship safe package-level iterations inside a shared workspace." engine: "Plan -> implement -> validate -> coordinate with monorepo release flow." fog: "Drift risk if package scripts diverge from monorepo root conventions."

@tryinget/pi-better-openai

Standalone Pi extension package extracted from contrib/pi-better-openai for focused OpenAI capabilities:

• /fast toggles OpenAI priority service tier injection (service_tier: "priority"). It defaults to every model exposed through the openai-codex provider (openai-codex/*).

• /pro toggles GPT-5.6 Sol Pro request injection (reasoning.mode: "pro") independently of Pi's reasoning effort. It defaults to exact openai-codex/gpt-5.6-sol and openai/gpt-5.6-sol model routes.

• In UI modes, fast state is published through Pi footer status key better-openai-fast (🐇/🐢), while Pro injection eligibility is shown under better-openai-pro (P+/P−).

• /openai-image and the openai_image tool generate or edit images through OpenAI Codex subscription auth and the hosted image_generation tool.

• Workspace path: packages/pi-better-openai

• Release component key: pi-better-openai

• Release config mode: component (default: component)

Runtime dependencies

This package expects pi host runtime APIs and declares them as peerDependencies:

• @earendil-works/pi-coding-agent
• @earendil-works/pi-ai
• @earendil-works/pi-tui

When using UI APIs (ctx.ui), guard interactive-only behavior with ctx.hasUI so pi -p non-interactive runs stay stable.

Commands and tools

• /fast — toggle fast mode for configured models. supportedModels accepts either a provider wildcard such as openai-codex/* or an exact provider/model key.
• /pro — toggle reasoning.mode: "pro" injection for configured GPT-5.6 Sol Responses API routes. The separate Pi thinking level still controls reasoning.effort.
• /openai-image <prompt> — generate an image from a prompt.
• /openai-settings — show fast-mode, Pro-injection, and image-generation diagnostics.
• openai_image tool — generate/edit images from model tool use; accepts prompt, optional images, action, model, outputFormat, save, and saveDir.

Image generation uses openai-codex OAuth credentials from Pi's model registry or ~/.pi/agent/auth.json; run /login openai-codex if credentials are missing.

GPT-5.6 Pro mode

OpenAI documents Sol, Terra, and Luna as distinct GPT-5.6 model tiers. Pro is a separate Responses API reasoning mode, not the setting that selects among those tiers. The request shape is:

{
  "model": "gpt-5.6-sol",
  "reasoning": {
    "effort": "high",
    "mode": "pro"
  }
}

/pro preserves any existing reasoning.effort, reasoning.summary, and future reasoning fields. Fast and Pro can be enabled together. Pro defaults off and is restricted to exact Sol routes using openai-responses or openai-codex-responses; project-local Pro configuration is ignored until Pi trusts that project.

The public openai Responses API behavior is documented by OpenAI. The ChatGPT subscription openai-codex backend is a separate endpoint, so this package treats Codex Pro injection as an operator-enabled compatibility bridge rather than proof that the backend honored the mode. /openai-settings reports request injection, not upstream effective-mode confirmation.

Radius routes currently use Pi's pi-messages gateway transport, whose client contract exposes reasoning effort but not Responses API reasoning.mode. Adding radius/gpt-5.6-sol to models.json, supportedModels, or a provider wildcard would only change catalog/allowlist data; it would not carry Pro mode to the upstream OpenAI request. Use a listed direct Responses API route until the Radius gateway and Pi pi-messages contract explicitly add and attest a Pro-mode field.

Configure global or trusted-project defaults in better-openai.json:

{
  "pro": {
    "desiredActive": false,
    "supportedModels": [
      "openai-codex/gpt-5.6-sol",
      "openai/gpt-5.6-sol"
    ]
  }
}

Use --pro to request Pro injection for one Pi startup without changing the persisted default.

The Pro implementation lives in extensions/pro.ts. extensions/fast.ts remains the package entrypoint and registers that module once so Fast, Pro, image support, and /openai-settings retain one installed package surface. pro.ts is an internal registration module, not a second package.json#pi.extensions entrypoint.

Package checks

Run from package directory:

npm install
npm run check

Run from monorepo root through the canonical package gate:

bash ./scripts/package-quality-gate.sh ci packages/pi-better-openai

The generated package-local scripts/quality-gate.sh is a thin wrapper that searches upward for the canonical monorepo root gate. If you validate the package outside the monorepo tree, set PACKAGE_QUALITY_GATE_SCRIPT to the canonical pi-extensions root gate path.

AK task/work-item operations

This package is a monorepo member, not a git root. Use the monorepo-root AK wrapper for task/work-item operations:

# from the monorepo root
./scripts/ak.sh --doctor
./scripts/ak.sh task ready

# from this package directory
../../scripts/ak.sh --doctor
../../scripts/ak.sh task show <id> -F json

Documentation placement

Use:

• docs/project/ for dated RFCs, runbooks, and evidence/progress notes
• docs/adr/ for adopted architecture decisions

Avoid creating new package-local docs/dev/ trees.

Live package activation

Install the package into Pi from the package directory containing this package's package.json:

pi install /absolute/path/to/your/monorepo/packages/pi-better-openai

Then in Pi:

1. run /reload
2. verify with a real command or tool call from this package

Release metadata

This scaffold keeps npm identity separate from release component identity:

• npm package name: @tryinget/pi-better-openai
• release component/tag stem: pi-better-openai (for example pi-better-openai-vX.Y.Z)

The npm package name must stay scoped. The release component should usually stay unscoped so root release-please component tags remain readable and stable.

This scaffold writes component metadata in package.json under x-pi-template:

• workspacePath
• releaseComponent
• releaseConfigMode

Default releaseConfigMode is component, meaning the package expects root-managed component release metadata such as a monorepo release-please component map. Use none only as an explicit opt-out when the monorepo root deliberately manages releases another way.

Use these values when wiring monorepo-level release-please component maps.

Docs discovery

npm run docs:list
npm run docs:list:workspace
npm run docs:list:json

Stack lane companions

This package follows the shared pi-ts lane. Add companions only when they materially improve clarity or reuse:

• fast-check for parser/rendering/selection invariants
• @cucumber/cucumber for executable Gherkin/operator workflows
• nunjucks for reusable text/config/prompt/file templates
• engineering-pi-ts.ts-quality.md when the package explicitly adopts deterministic screening with ts-quality

If this package adopts ts-quality, prefer repo-local rollout truth in docs/project/ts-quality-current-vs-target.md and keep the detailed adoption doctrine upstream in ~/ai-society/softwareco/owned/ts-quality/docs/adoption/.

Copier lifecycle policy

• Keep .copier-answers.yml committed.
• Do not edit .copier-answers.yml manually.
• Run update/recopy from a clean destination repo (commit or stash pending changes first).
• Use copier update --trust when .copier-answers.yml includes _commit and update is supported.
• In non-interactive shells/CI, append --defaults to update/recopy.
• Use copier recopy --trust when update is unavailable (for example local non-VCS source) or cannot reconcile cleanly.
• After recopy, re-apply local deltas intentionally and run npm run check.