---
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:

```json
{
  "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`:

```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:

```bash
npm install
npm run check
```

Run from monorepo root through the canonical package gate:

```bash
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:

```bash
# 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`:

```bash
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

```bash
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`.