summary: "@tryinget/pi-session-compaction package overview." read_when:

• "Orienting to this package or directory before changing its behavior."

@tryinget/pi-session-compaction

Dedicated Pi package for custom session compaction summaries.

Live posture

This package is now the local live owner for custom session_before_compact summaries after an explicit cutover preflight found no other installed compaction override packages.

• exposes package.json#pi.extensions through extensions/session-compaction.js
• registers input tracking for preserving slash-command prompts
• registers exactly one session_before_compact handler through the fail-closed registration guard
• exposes /compact-focus, a guided operator menu that calls the same compaction path with selected custom instructions
• exposes /compact-handoff and the session_compaction_handoff tool for owner-owned, operator-pasteable fresh-session handoff prompts before compaction/reload; the tool accepts structured discovery/promotion-status records for insights that still need owner-surface promotion
• exports @tryinget/pi-session-compaction/handoff-generation, which reduces the live branch, accepts bounded Git/AK readback from the transport owner, calls the public host-owned ctx.modelRegistry.complete() API, and validates one self-contained prompt for clean-session transport such as pi-little-helpers /handoff-tab; this generator does not launch terminals or submit messages itself
• does not expose prompt bundles or package.json#pi.prompts
• falls back to stock compaction when the custom summarizer cannot be resolved, except explicit malformed/preset-directed paths that intentionally cancel rather than silently producing the wrong preset summary
• delegates summary model calls to the public host ctx.modelRegistry.complete() API, while keeping provider registration, authentication, and custom stream overrides in the Pi host rather than importing pi-ai inside the extension

For reasoning models whose public raw API requires context-aware token-budget translation that Pi does not expose to extensions (currently non-adaptive Anthropic and non-adaptive Bedrock Claude), the adapter fails closed. Ordinary compaction then uses Pi's stock compaction path; explicit preset compaction remains cancelled rather than silently changing models. Model-generated handoff generation has no stock fallback and reports the incompatibility.

After local install, reload Pi with /reload before expecting the current session process to use the new hook.

Ownership

This package is the intended single owner of custom session_before_compact summaries in the pi-extensions monorepo.

• pi-session-compaction owns custom summary content and shape.
• pi-autonomous-session-control remains the runtime/subagent/rewind owner and should only observe session_compact for rewind aliasing.
• Do not install/enable multiple custom compaction overrides at once.

Current slice

This package currently implements the compaction-facing foundations and a tested live handler module:

• current-session model fallback
• named preset resolution (exact, case-insensitive, prefix, normalized substring)
• prompt-template-model-aligned model fallback semantics imported from @tryinget/pi-model-selection: exact modelId, exact provider/modelId, comma-separated fallback lists, current-model preservation, and provider-priority ordering for ambiguous bare IDs
• host-availability-aware model selection through @tryinget/pi-model-selection without returning API keys, headers, or provider environment to the extension
• host-owned summary execution through a modelRegistry.complete() adapter and an executable Pi host contract test, with no extension-local pi-ai dependency or provider registry; the adapter allowlists package-owned request controls, translates normalized thinking into the selected API's public option shape, and fails closed when a model or API cannot honor the requested level
• normalized thinking levels
• files-touched collection ported from dot314 grounded-compaction, including read/write/edit/move/delete tracking, no-op edit filtering, move redirects, repo-relative display paths, and manifest rendering
• user prompt / command preservation ported from legacy pi-user-prompt-compaction, including expanded skill-block recovery, timestamp-matched slash command recovery, previous-summary prompt-section recovery, and /compact <customInstructions> preservation
• extensions/session-compaction/handler.js assembly for session_before_compact, including compact-instruction parsing, config loading, stock-boundary span derivation, summary prompt assembly, final files-touched manifest append, essential-prompt append/deduplication, safe stock fallback, and abort cancellation
• extensions/session-compaction/registration.js guard for hook activation, including default-disabled registration, explicit handler-test confirmation, explicit no-double-compaction preflight, existing-handler zero-count proof, duplicate package-registration blocking, and optional input tracking for slash-command preservation without slash-command registration
• live extensions/session-compaction.js entrypoint, which enables input tracking, guarded session_before_compact registration, and /compact-focus without adding prompt bundles
• non-live extensions/session-compaction/branch-summary.js helpers for optional session_before_tree augmentation, including prompt-contract loading, files-touched instructions, focus text preservation, and safe undefined-on-failure behavior
• extensions/session-compaction/handoff-prompt.js for the canonical fresh-session prompt affordance, including linked discovery records with valuable-discovery, source, promotion-status, owner-surface, metric, falsifier, and non-authorization fields; ASC/self may route or provide mirror-only cues, but this package owns compaction/handoff prompt shape
• extensions/session-compaction/handoff-generation.js for conversation-grounded handoffs: latest-compaction branch reduction, explicit operator goal/cwd, host-model generation at low reasoning, exact fresh-session prefix validation, and a 96 KiB launch boundary
• clear failure messages for missing models, ambiguous matches, unsupported reasoning, and incompatible registries

The live hook should remain the only custom compaction override. If another compaction owner is installed later, remove or disable one before reloading Pi.

Template baseline

This package was reconciled through ../pi-extensions-template in simple-package mode, then intentionally adapted for the current compaction foundation. It keeps template lineage and baseline files such as .copier-answers.yml, biome.jsonc, policy/engineering-lane.json, and docs/engineering.local.md. It exposes package.json#pi.extensions for the live hook and /compact-focus, but still deliberately omits package.json#pi.prompts.

Target summary shape

## Brief
- Current objective
- Current state
- Immediate next action

## Constraints & preferences
- User-stated constraints and preferences

## Key decisions & rejected paths
- Decisions
- Failed/rejected approaches worth not repeating

## Status
- Done
- In progress
- Unverified
- Blocked

## Valuable discoveries and promotion status
- Strategic session-only insights that must survive reload
- Source and owner surface for promotion
- Promoted, deferred, or still needs exact promotion action
- Metrics, falsifiers, and non-authorizations

## Open issues and uncertainties
- Facts vs inferences

## Immediate next steps
1. Concrete next action
2. Validation
3. Follow-up

## Mandatory reading
- exact/file/path.ts
- docs/exact-doc.md

## Essential user prompts / commands + arguments used
1. original user request
2. /skill:frontend-design ...
3. /template:review ...

---

## Files touched (cumulative)
R=read, W=write, E=edit, M=move/rename, D=delete

```text
RE src/foo.ts
W  src/bar.ts
```

Design inputs

The full implementation should port and reconcile these sources:

• grounded compaction foundation from softwareco/contrib/dot314/extensions/grounded-compaction/
• files-touched core from softwareco/contrib/dot314/extensions/_shared/files-touched-core.ts
• user prompt/command preservation from legacy ~/programming/pi-extensions/pi-user-prompt-compaction
• installed prompt frontmatter model semantics from npm:pi-prompt-template-model (/home/tryinget/.npm-global/lib/node_modules/pi-prompt-template-model/model-selection.ts and prompt-loader.ts)
• observed prompt-template model lifecycle ideas from packages/pi-prompt-template-accelerator/src/ptxRuntimeRegistry.js

The live /commit prompt now gets its model behavior from packages/pi-prompt-template-execution, not from Pi core prompt-template loading and not from pi-prompt-template-accelerator. The shared resolver semantics live in packages/pi-model-selection (@tryinget/pi-model-selection): exact specs, comma fallback, current-model preservation, auth-aware candidate selection, and provider priority openai-codex -> anthropic -> github-copilot -> openrouter. This package keeps only compaction-specific preset, thinking, and summarizer resolution logic.

Validation

cd packages/pi-session-compaction
npm run test
npm run check

Next implementation steps

1. Reload Pi after local install and observe one real compaction event before treating the cutover as fully proven in the active operator session.
2. Keep branch-tree summary augmentation non-live unless a separate plan explicitly enables session_before_tree behavior.
3. Preserve the no-double-compaction invariant before any future package install/reload.