How pi-web Handles Session Compaction Events Across pi Versions

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 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).

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

// 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. 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 functions regardless of agent version.
• Result parsing: The 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 to decode the payload and refresh the session tree with the compacted data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}