# How pi-web Handles Session Compaction Events Across pi Versions

> Learn how pi-web normalizes session compaction events across pi versions ensuring seamless UI functionality with the useAgentSession hook.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: internals
- Published: 2026-07-26

---

**Pi-web normalizes both legacy `auto_compaction_*` and modern `compaction_*` event names in the `useAgentSession` hook to ensure the UI works seamlessly across all pi agent versions.**

The `agegr/pi-web` repository provides a React-based interface for interacting with the π agent. Because the agent renamed its compaction lifecycle events between versions 0.6 and 0.7, pi-web implements a version-agnostic event handler that processes both naming conventions to maintain backward compatibility.

## The Evolution of Compaction Event Names in pi

The π agent changed its event naming convention to signal session compaction lifecycles:

| π Version | Start Event | End Event |
|-----------|-------------|-----------|
| **≤ v0.6** | `auto_compaction_start` | `auto_compaction_end` |
| **≥ v0.7** | `compaction_start` | `compaction_end` |

Both event pairs represent the same underlying operation—automatic compaction of conversation history—but the "auto\_" prefix was removed in newer versions.

## Normalizing Events in the useAgentSession Hook

The `useAgentSession` hook in [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts) deliberately listens for both sets of event names to support mixed-version deployments.

When a start event arrives—whether `auto_compaction_start` or `compaction_start`—the handler sets the local `isCompacting` state to **`true`**, clears any previous error or result state, and exposes the "Stop compaction" button to the user (lines 1006-1010).

When an end event arrives (`auto_compaction_end` or `compaction_end`), the hook resets `isCompacting` to **`false`**. If the event payload contains an error message, that error is stored directly; otherwise, the compacted result is parsed via `readCompactResult` and the session reloads to display the updated message tree (lines 1012-1021).

```tsx
// Example: React component that shows a spinner while a compaction is running
import { useAgentSession } from '@/hooks/useAgentSession';

export function CompactionStatus({ sessionId }: { sessionId: string }) {
  const { isCompacting, compactError, compactResult, sendAgentCommand } =
    useAgentSession(sessionId);

  // Abort button – works for any π version
  const abort = async () => {
    await sendAgentCommand(sessionId, { type: 'abort_compaction' });
  };

  return (
    <>
      {isCompacting && (
        <div className="compaction">
          <p>Compacting session…</p>
          <button onClick={abort}>Stop compaction</button>
        </div>
      )}
      {compactError && <p className="error">{compactError}</p>}
      {compactResult && <pre>{JSON.stringify(compactResult, null, 2)}</pre>}
    </>
  );
}

```

## Aborting Compactions via RPC Commands

The UI exposes an **abort mechanism** through the `abort_compaction` command defined in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) (lines 480-483). This command works across all π versions because the RPC layer forwards the request directly to the agent, which determines whether a compaction is currently in progress.

You can also trigger compaction manually by sending the `set_auto_compaction` command:

```ts
// Example: Manually triggering a compaction from the client side
import { sendAgentCommand } from '@/lib/agent-client';

// `sessionId` is the UUID of the current session
await sendAgentCommand(sessionId, { type: 'set_auto_compaction', enabled: true });
// The agent will emit `compaction_start` (or `auto_compaction_start`) and later
// `compaction_end` (or `auto_compaction_end`), which the UI will handle.

```

## Parsing Compaction Results with compaction-summary

After a successful compaction ends, pi-web processes the result payload using utilities in [`lib/compaction-summary.ts`](https://github.com/agegr/pi-web/blob/main/lib/compaction-summary.ts). This module decodes the binary or JSON result returned by the agent and converts it into a human-readable summary that the UI displays in the session view.

## Summary

- **Dual event support**: The `useAgentSession` hook handles both `auto_compaction_*` (legacy) and `compaction_*` (modern) event names.
- **State management**: Start events set `isCompacting` to true; end events reset it and process errors or results.
- **Version-agnostic aborts**: The `abort_compaction` command in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) functions regardless of agent version.
- **Result parsing**: The [`lib/compaction-summary.ts`](https://github.com/agegr/pi-web/blob/main/lib/compaction-summary.ts) module interprets post-compaction payloads for display.

## Frequently Asked Questions

### What is the difference between auto_compaction_start and compaction_start?

There is no functional difference. The π agent versions ≤ 0.6 used the `auto_compaction_*` prefix, while versions ≥ 0.7 dropped the prefix. Both events signal that an automatic compaction process has begun.

### How does pi-web maintain compatibility with older pi versions?

The `useAgentSession` hook explicitly checks for both naming conventions when processing WebSocket events. By normalizing the event names internally, the UI components remain unaware of which version they are communicating with.

### Can users abort an active compaction from the UI?

Yes. The `abort_compaction` command is available through the RPC manager and works across all supported π versions. When invoked, it requests the agent to terminate the current compaction process immediately.

### Where does pi-web parse the compaction results?

After receiving a compaction end event, pi-web uses the `readCompactResult` utility from [`lib/compaction-summary.ts`](https://github.com/agegr/pi-web/blob/main/lib/compaction-summary.ts) to decode the payload and refresh the session tree with the compacted data.