preemptive generation based on python library

Author: simllll

agents/src/llm/chat_context.ts

@@ -499,6 +499,113 @@ export class ChatContext {
     return await toChatCtx(format, this, injectDummyUserMessage);
   }
 
+  /**
+   * Compare this ChatContext with another for logical equivalence.
+   * Unlike strict equality, this method:
+   * - Ignores timestamps (createdAt fields)
+   * - Ignores other volatile metadata
+   * - Focuses on content: compares IDs, types, and payload
+   *
+   * This is useful for detecting if the conversation content has changed,
+   * for example when validating preemptive generation results.
+   *
+   * @param other - The ChatContext to compare with
+   * @returns true if both contexts contain the same sequence of items with matching essential fields
+   */
+  isEquivalent(other: ChatContext): boolean {
+    // Same object reference
+    if (this === other) {
+      return true;
+    }
+
+    // Different lengths
+    if (this._items.length !== other._items.length) {
+      return false;
+    }
+
+    // Compare each item pair
+    for (let i = 0; i < this._items.length; i++) {
+      const a = this._items[i]!;
+      const b = other._items[i]!;
+
+      // IDs and types must match
+      if (a.id !== b.id || a.type !== b.type) {
+        return false;
+      }
+
+      // Type-specific field comparison
+      if (a.type === 'message' && b.type === 'message') {
+        // Compare role, content, and interrupted status (not timestamp)
+        if (a.role !== b.role || a.interrupted !== b.interrupted) {
+          return false;
+        }
+
+        // Compare content arrays
+        if (a.content.length !== b.content.length) {
+          return false;
+        }
+
+        for (let j = 0; j < a.content.length; j++) {
+          const ca = a.content[j]!;
+          const cb = b.content[j]!;
+
+          // Both are strings
+          if (typeof ca === 'string' && typeof cb === 'string') {
+            if (ca !== cb) {
+              return false;
+            }
+          }
+          // Both are objects
+          else if (typeof ca === 'object' && typeof cb === 'object') {
+            if (ca.type !== cb.type) {
+              return false;
+            }
+
+            if (ca.type === 'image_content' && cb.type === 'image_content') {
+              // Compare essential image fields (not cache)
+              if (
+                ca.id !== cb.id ||
+                ca.image !== cb.image ||
+                ca.inferenceDetail !== cb.inferenceDetail ||
+                ca.inferenceWidth !== cb.inferenceWidth ||
+                ca.inferenceHeight !== cb.inferenceHeight ||
+                ca.mimeType !== cb.mimeType
+              ) {
+                return false;
+              }
+            } else if (ca.type === 'audio_content' && cb.type === 'audio_content') {
+              // Compare audio transcript (frames comparison would be too expensive)
+              if (ca.transcript !== cb.transcript) {
+                return false;
+              }
+            }
+          }
+          // Mismatched types
+          else {
+            return false;
+          }
+        }
+      } else if (a.type === 'function_call' && b.type === 'function_call') {
+        // Compare name, callId, and args (not timestamp)
+        if (a.name !== b.name || a.callId !== b.callId || a.args !== b.args) {
+          return false;
+        }
+      } else if (a.type === 'function_call_output' && b.type === 'function_call_output') {
+        // Compare name, callId, output, and isError (not timestamp)
+        if (
+          a.name !== b.name ||
+          a.callId !== b.callId ||
+          a.output !== b.output ||
+          a.isError !== b.isError
+        ) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
   /**
    * Internal helper used by `truncate` & `addMessage` to find the correct
    * insertion index for a timestamp so the list remains sorted.