The Responses API Compaction Progress Event: response.compaction.compacting and compaction_trigger

The longer an agent session runs, the tighter the context window gets — and compaction is the Responses API answer. On 2026-09-16, openai-node v7.17.0 (released 19:23 UTC) completed the observability picture for that machinery with a new streaming event: response.compaction.compacting (PR #2749). It is a heartbeat for the compaction process — it tells the client that compaction is advancing, while deliberately carrying no summary content at all. Based on type definitions and spec text extracted from the v7.17.0 tag on the day of release, this article walks through the event semantics, its fields, where it sits in the broader compaction surface, and the Python-side gap.

Update note (2026-09-19): when this article was written, Python had not caught up yet; openai-python v3.15.0 (released 2026-09-18, PR #3866) now ships the same event — ResponseCompactionCompactingEvent (a beta variant, BetaResponseCompactionCompactingEvent, with an optional agent field), with fields type / item_id / output_index / sequence_number, matching the node side. Every statement below that says Python lacks the event as of v3.14.1, or that the event is node-only, is a record of the 2026-09-17 check; the current state is the one in this note. For the full breakdown see openai-python 3.15/3.16 and openai-node 7.18/7.19: Cache Prewarming, Webhook Management, connector_id Deprecation.

1. Overview: a heartbeat with no payload

The spec describes the event in two sentences: "Emitted when new summary content is sampled for a compaction trigger. Contains no summary content." The expanded behavioral constraints are more specific:

• Throttled: while processing a compaction_trigger, the event reports newly sampled summary output at most once every 30 seconds;
• No content: the event carries no summary content and does not modify the compaction output item;
• Separate lifecycle: the compaction output item is still created and completed by the existing response.output_item.added / response.output_item.done events, and done carries the final encrypted content of that item;
• Not guaranteed: a short compaction may finish without emitting a progress event at all.

Together these constraints signal the design intent: the progress event exists purely for observability (so a UI can show a "compacting" state), while content delivery and completion detection stay on the existing output-item lifecycle — client state machines gain no mandatory new step.

2. Event fields and the three shapes

In its standard (HTTP streaming) shape the event object has exactly four fields, all positional:

Two variants each add a single optional field:

The WebSocket documentation adds one more sentence: compaction progress follows the same cadence and output-item lifecycle described for HTTP streaming — the semantics are identical across both transports.

3. The compaction surface: where this event fits

response.compaction.compacting does not introduce a new capability — it adds progress observability to a system that already existed. Every row but the last in the table below was verified against the v7.16.0 / v3.12.0 tags while writing this article; none of them ship in this batch.

In other words: triggering works through the input item or the config, artifacts flow through the output item or the REST endpoint, and v7.17.0 adds the signal of how far along the process is. The SDK implementation confirms the positioning — the node package's internal response accumulator registers the event as an ignored progress record scoped to the compaction output item type, so it never accumulates into output content.

4. Minimal integration examples

The examples below use only patterns verified against the v7.17.0 tag (docs-checked, not run against the live API; sources: docs/responses.md and src/resources/responses/responses.ts).

Trigger side — put the compaction trigger last in the input array:

import OpenAI from 'openai';

const client = new OpenAI();

const response = await client.responses.create({
  model: 'gpt-5.6-terra',
  input: [
    { role: 'user', content: 'Turn this meeting transcript into action items.' },
    // ...earlier long-context input items omitted...
    { type: 'compaction_trigger' }, // must be the final input item
  ],
});

HTTP streaming side — recognize the progress event, but never expect content from it:

// Event handling branch (excerpt): use the progress event only for a "compacting" indicator
function handleEvent(event: { type: string }) {
  switch (event.type) {
    case 'response.compaction.compacting':
      // item_id / output_index / sequence_number locate the compaction item
      // Note: no summary content here; completion is signaled by output_item.done
      showCompactingIndicator();
      break;
    case 'response.output_item.done':
      hideCompactingIndicator();
      break;
  }
}

WebSocket side (requires the optional ws peer dependency on Node): the WebSocket variant adds the optional stream_id, everything else is identical:

import OpenAI from 'openai';
import { ResponsesWS } from 'openai/resources/responses/ws';

const client = new OpenAI();
const socket = new ResponsesWS(client);

socket.on('event', (event) => {
  if (event.type === 'response.compaction.compacting') {
    // event.stream_id is present only when the response.create supplied one
    console.log('compacting', event.item_id, event.output_index);
  }
});

5. Versions and the cross-package gap

• openai-node v7.17.0 (2026-09-16T19:23 UTC): the event lands in both the standard and beta responses types; the same spec sync renamed the compact endpoint summary to "Compact conversation" and documented the progress cadence in the WebSocket docs.
• openai-python as of v3.14.1 (released 2026-09-15T23:12 UTC, the latest Python release on the day of writing): api.md listed no CompactingEvent and the tag tree contained no corresponding type file (both checked on 2026-09-17 via the raw file and the git trees API — zero hits). The event was node-first at the time — that gap closed on 2026-09-18 with python v3.15.0 (see the update note at the top). The two packages never had matching version numbers, and one API change landing in different releases per package is the norm.
• Baseline attribution: the four pre-existing components in the section 3 table are not new in this batch — the node v7.16.0 (2026-09-15) responses.ts and api.md already contain the compaction_trigger input item, the context_management config, the compact endpoint, and the compaction item types, and the python v3.12.0 (2026-09-10) tag tree already had the compaction item and compact params type files (each checked individually on 2026-09-17).

6. Common pitfalls

• Reading the progress event as a content event: there is no summary content in it — by explicit design, not by omission. The summary lives in the encrypted_content of the compaction item carried by response.output_item.done.
• Making the progress event mandatory in your state machine: short compactions may emit none. Anchor completion on output_item.done; use the progress event only for UI hints or logging.
• Ignoring ownership in beta multi-agent streams: when several agents compact concurrently, distinguish events with the optional agent.agent_name; BetaResponseCompactionItem carries the same field.
• Expecting stream_id to always be there over WebSocket: it appears only when the originating response.create supplied one — treat it as optional.
• Conflating /responses/compact with streaming progress: the REST endpoint returns the compaction result in one call; the progress event serves observation during streaming. Their inputs and outputs differ.

7. Next steps

• gpt-6-astra appears in the OpenAI SDK: the new ChatModel ID and the Safety Alerts API — the breakdown of the context_management config (automatic compaction trigger with a token threshold) is in its section 5.
• Codex CLI 0.154.0 and SDK 0.154.0: Worktrees, ExternalMessage, and the ultra Reasoning Effort — product-level compaction behavior in Codex CLI, a different layer from the API events in this article.
• The Agents API appears in the OpenAI SDK (beta): /agents CRUD, environments, sessions, and vaults — the multi-agent background that the beta variant's agent.agent_name is built for.
• The Live API lands in the OpenAI SDK: gpt-live-1, dual WebRTC/WebSocket channels, and SIP call control — the other WebSocket-based real-time surface.
• Responses API advanced: structured outputs, streaming SSE, Batch API, prompt caching — the mechanics behind streaming consumption and long contexts.
• openai-python 3.14.x and openai-node 7.16/7.17: Stream Error Normalization, WebSocket Backpressure, and SSE Fixes — the full reliability picture of the same release wave, including WebSocket iterator backpressure.
• openai-python 3.15/3.16 and openai-node 7.18/7.19: Cache Prewarming, Webhook Management, connector_id Deprecation — the batch (v3.15.0) that brought this event to the Python side, in full.
• OpenAI Models Release Notes (2026, Living Document) — every release on one timeline.