pi-coax

pi-coax is a project-local Pi extension that coaxes an assistant through a lightweight execution-control loop.

Current behavior

The extension injects four kinds of guidance into a Pi agent run:

• PLAN — added once at the start of a user request. It asks the assistant to write an explicit <plan>...</plan> before using tools.
• INSPECT — scheduled after a configured number of tool-call rounds. It asks the assistant to compare progress against the original plan and current evidence.
• EVOLVE — scheduled after detected tool failures, up to a configured cap. It asks the assistant to diagnose the failed assumption and revise only the unsupported remainder of the plan.
• VERIFY — queued as a final follow-up after primary execution. It asks the assistant to check requirements, unknowns, validation, and whether the result addresses the user objective.

This release is intentionally prompt-orchestration only. It does not use Pi context or tool_call hooks, block or rewrite ordinary tool calls, parse AGENTS.md independently, write design files, or call a separate LLM judge.

Repository layout

.pi/extensions/coax/index.ts        Extension entry point and Pi lifecycle wiring
.pi/extensions/coax/prompts.ts      PLAN / INSPECT / EVOLVE / VERIFY prompt text
.pi/extensions/coax/state.ts        Run state, counters, scheduling, plan/failure capture
.pi/extensions/coax/commands.ts     /coax-* command registration
.pi/extensions/coax/config.ts       .pi/coax.json loading and normalization
.pi/extensions/coax/trace.ts        JSONL trace writing
.pi/extensions/coax/result-utils.ts Tool result summarization and secret redaction
.pi/extensions/coax/tests/          Unit and lifecycle tests
.pi/coax.json                       Project-local runtime configuration
docs/                                Design notes
scripts/coax-lifecycle-spike.ts     Manual lifecycle logging extension for real Pi sessions
types/                               Local type shims for testing without Pi installed

Install in a Pi project

Install the package globally or locally with Pi:

pi install npm:pi-coax
# or for one run only:
pi -e npm:pi-coax

For local development, build first and install from this checkout:

npm run build
pi install /absolute/path/to/pi-coax

After the target project is trusted, Pi loads the packaged extension declared in package.json under the pi.extensions manifest.

Configuration

Configuration is read from .pi/coax.json:

{
  "enabled": true,
  "inspectEveryToolRounds": 3,
  "maxEvolves": 3,
  "showInjectedMessages": false,
  "writeTrace": true,
  "failureDetection": {
    "toolErrors": true,
    "emptyResults": false
  }
}

Options:

• enabled — turns the extension on or off.
• inspectEveryToolRounds — schedules INSPECT after this many tool-result turns. Parallel tool calls in one assistant turn count as one round.
• maxEvolves — maximum automatic EVOLVE checkpoints per request.
• showInjectedMessages — whether injected custom messages are displayed.
• writeTrace — writes lightweight JSONL traces under .pi/coax-traces/.
• failureDetection.toolErrors — records failed tool results as EVOLVE triggers.
• failureDetection.emptyResults — optionally treats empty successful tool output as a failure signal.

Commands

• /coax-status — show active run phase, counters, and trace path.
• /coax-trace — show the current trace path and run statistics.
• /coax-enable — set .pi/coax.json enabled to true.
• /coax-disable — set .pi/coax.json enabled to false.
• /coax-inspect-now — manually queue the same INSPECT prompt used by the scheduler.

Traces

When writeTrace is enabled, each request gets one JSONL trace under .pi/coax-traces/.

Traces include lightweight metadata such as:

• prompt hash, run id, context-file count, selected tool names, and prompt-guideline count;
• whether a plan block was observed;
• short redacted tool input/output summaries;
• injected INSPECT/EVOLVE/VERIFY events;
• final run counters.

Traces intentionally do not store full system prompts, context file contents, complete tool output, private reasoning, or unredacted common secret patterns.

Development

Install dependencies from the lockfile:

npm ci

Run validation:

npm test
npm run typecheck
npm run build

The test suite uses Node's built-in test runner plus local type shims, so Pi does not need to be installed for unit tests. Current coverage includes prompt snapshots, scheduling behavior, lifecycle injection, state/stat helpers, and result summarization/redaction.

Manual lifecycle spike

scripts/coax-lifecycle-spike.ts is a disposable logging extension for validating real Pi event order, especially follow-up delivery from agent_end and verification passes that call tools.

To use it temporarily, copy it into a Pi project as .pi/extensions/coax-lifecycle-spike.ts, run the lifecycle scenarios you care about, inspect .pi/coax-traces/lifecycle-spike.jsonl, then remove it.