revisit the design:

- removed compactionThreshold, countCompactionItems
- instead, added general callback named shouldTriggerCompaction
- added compactionCandidateItems, sessionItems, and responseId for custom shouldTriggerCompaction logic

Author: seratch

examples/memory/oai-compact.ts

@@ -9,17 +9,22 @@ import { FileSession } from './sessions';
 
 async function main() {
   const session = new OpenAIResponsesCompactionSession({
+    model: 'gpt-5.2',
     // This compaction decorator handles only compaction logic.
     // The underlying session is responsible for storing the history.
     underlyingSession: new FileSession(),
-    // Set a low threshold to observe compaction in action.
-    compactionThreshold: 3,
-    model: 'gpt-4.1',
+    // (optional customization) This example demonstrates the simplest compaction logic,
+    // but you can also estimate the context window size using sessionItems (all items)
+    // and trigger compaction at the optimal time.
+    shouldTriggerCompaction: ({ compactionCandidateItems }) => {
+      // Set a low threshold to observe compaction in action.
+      return compactionCandidateItems.length >= 4;
+    },
   });
 
   const agent = new Agent({
     name: 'Assistant',
-    model: 'gpt-4.1',
+    model: 'gpt-5.2',
     instructions:
       'Keep answers short. This example demonstrates responses.compact with a custom session. For every user turn, call fetch_image_data with the provided label. Do not include raw image bytes or data URLs in your final answer.',
     modelSettings: { toolChoice: 'required' },
@@ -66,10 +71,19 @@ async function main() {
     }
 
     const compactedHistory = await session.getItems();
-    console.log('\nStored history after compaction:');
+    console.log('\nHitory including both compaction and newer items:');
     for (const item of compactedHistory) {
       console.log(`- ${item.type}`);
     }
+
+    // You can manually run compaction this way:
+    await session.runCompaction({ force: true });
+
+    const finalHistory = await session.getItems();
+    console.log('\nStored history after final compaction:');
+    for (const item of finalHistory) {
+      console.log(`- ${item.type}`);
+    }
   });
 }
 

packages/agents-core/src/memory/session.ts

@@ -51,9 +51,13 @@ export type OpenAIResponsesCompactionArgs = {
   /**
    * The `response.id` from a completed OpenAI Responses API turn, if available.
    *
-   * When undefined, compaction should be skipped.
+   * When omitted, implementations may fall back to a cached value or throw.
    */
-  responseId: string | undefined;
+  responseId?: string | undefined;
+  /**
+   * When true, compaction should run regardless of any internal thresholds or hooks.
+   */
+  force?: boolean;
 };
 
 export interface OpenAIResponsesCompactionAwareSession extends Session {
@@ -66,7 +70,7 @@ export interface OpenAIResponsesCompactionAwareSession extends Session {
    * This hook is best-effort. Implementations should consider handling transient failures and
    * deciding whether to retry or skip compaction for the current turn.
    */
-  runCompaction(args: OpenAIResponsesCompactionArgs): Promise<void> | void;
+  runCompaction(args?: OpenAIResponsesCompactionArgs): Promise<void> | void;
 }
 
 export function isOpenAIResponsesCompactionAwareSession(

packages/agents-core/src/runImplementation.ts

@@ -2291,10 +2291,13 @@ async function runCompactionOnSession(
   session: Session | undefined,
   responseId: string | undefined,
 ): Promise<void> {
-  if (isOpenAIResponsesCompactionAwareSession(session)) {
-    // Called after a completed turn is persisted so compaction can consider the latest stored state.
-    await session.runCompaction({ responseId });
+  if (!isOpenAIResponsesCompactionAwareSession(session)) {
+    return;
   }
+  // Called after a completed turn is persisted so compaction can consider the latest stored state.
+  await session.runCompaction(
+    typeof responseId === 'undefined' ? undefined : { responseId },
+  );
 }
 
 /**

packages/agents-core/test/runImplementation.test.ts

@@ -634,6 +634,84 @@ describe('saveToSession', () => {
     expect(session.events).toEqual(['addItems:2', 'runCompaction:resp_123']);
     expect(session.items).toHaveLength(2);
   });
+
+  it('invokes runCompaction when responseId is undefined', async () => {
+    class TrackingSession implements Session {
+      items: AgentInputItem[] = [];
+      events: string[] = [];
+
+      async getSessionId(): Promise<string> {
+        return 'session';
+      }
+
+      async getItems(): Promise<AgentInputItem[]> {
+        return [...this.items];
+      }
+
+      async addItems(items: AgentInputItem[]): Promise<void> {
+        this.events.push(`addItems:${items.length}`);
+        this.items.push(...items);
+      }
+
+      async popItem(): Promise<AgentInputItem | undefined> {
+        return undefined;
+      }
+
+      async clearSession(): Promise<void> {
+        this.items = [];
+      }
+
+      async runCompaction(args?: { responseId?: string }): Promise<void> {
+        this.events.push(`runCompaction:${String(args?.responseId)}`);
+      }
+    }
+
+    const textAgent = new Agent<UnknownContext, 'text'>({
+      name: 'Recorder',
+      outputType: 'text',
+      instructions: 'capture',
+    });
+    const agent = textAgent as unknown as Agent<
+      UnknownContext,
+      AgentOutputType
+    >;
+    const session = new TrackingSession();
+    const context = new RunContext<UnknownContext>(undefined as UnknownContext);
+    const state = new RunState<
+      UnknownContext,
+      Agent<UnknownContext, AgentOutputType>
+    >(context, 'hello', agent, 10);
+
+    state._modelResponses = [];
+    state._generatedItems = [
+      new MessageOutputItem(
+        {
+          type: 'message',
+          role: 'assistant',
+          id: 'msg_123',
+          status: 'completed',
+          content: [
+            {
+              type: 'output_text',
+              text: 'here is the reply',
+            },
+          ],
+          providerData: {},
+        },
+        textAgent,
+      ),
+    ];
+    state._currentStep = {
+      type: 'next_step_final_output',
+      output: 'here is the reply',
+    };
+
+    const result = new RunResult(state);
+    await saveToSession(session, toInputItemList(state._originalInput), result);
+
+    expect(session.events).toEqual(['addItems:2', 'runCompaction:undefined']);
+    expect(session.items).toHaveLength(2);
+  });
 });
 
 describe('prepareInputItemsWithSession', () => {

packages/agents-openai/src/index.ts

@@ -26,4 +26,5 @@ export {
 export {
   OpenAIResponsesCompactionSession,
   type OpenAIResponsesCompactionSessionOptions,
+  type OpenAIResponsesCompactionDecisionContext,
 } from './memory/openaiResponsesCompactionSession';