From 3de559ff87cab398c3ed7eaf34cde3cd7cedaa09 Mon Sep 17 00:00:00 2001
From: Kenny <gh@alias.kdco.llc>
Date: Wed, 14 Jan 2026 21:06:26 -0500
Subject: [PATCH] refactor: rename getNewMessages to consumeNewMessages

Rename to signal mutation behavior - the function advances the cursor
as a side effect, so 'consume' better reflects that calling it twice
with the same input yields different results.
---
 src/shared/session-cursor.test.ts  | 20 ++++++++++----------
 src/shared/session-cursor.ts       |  2 +-
 src/tools/background-task/tools.ts |  4 ++--
 src/tools/call-omo-agent/tools.ts  |  4 ++--
 4 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/shared/session-cursor.test.ts b/src/shared/session-cursor.test.ts
index 2edf1e16..4ef0ff8d 100644
--- a/src/shared/session-cursor.test.ts
+++ b/src/shared/session-cursor.test.ts
@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it } from "bun:test"
-import { getNewMessages, resetMessageCursor } from "./session-cursor"
+import { consumeNewMessages, resetMessageCursor } from "./session-cursor"
 
-describe("getNewMessages", () => {
+describe("consumeNewMessages", () => {
   const sessionID = "session-123"
 
   const buildMessage = (id: string, created: number) => ({
@@ -17,8 +17,8 @@ describe("getNewMessages", () => {
     const messages = [buildMessage("m1", 1), buildMessage("m2", 2)]
 
     // #when
-    const first = getNewMessages(sessionID, messages)
-    const second = getNewMessages(sessionID, messages)
+    const first = consumeNewMessages(sessionID, messages)
+    const second = consumeNewMessages(sessionID, messages)
 
     // #then
     expect(first).toEqual(messages)
@@ -28,11 +28,11 @@ describe("getNewMessages", () => {
   it("returns only new messages after cursor advances", () => {
     // #given
     const messages = [buildMessage("m1", 1), buildMessage("m2", 2)]
-    getNewMessages(sessionID, messages)
+    consumeNewMessages(sessionID, messages)
     const extended = [...messages, buildMessage("m3", 3)]
 
     // #when
-    const next = getNewMessages(sessionID, extended)
+    const next = consumeNewMessages(sessionID, extended)
 
     // #then
     expect(next).toEqual([extended[2]])
@@ -41,11 +41,11 @@ describe("getNewMessages", () => {
   it("resets when message history shrinks", () => {
     // #given
     const messages = [buildMessage("m1", 1), buildMessage("m2", 2)]
-    getNewMessages(sessionID, messages)
+    consumeNewMessages(sessionID, messages)
     const shorter = [buildMessage("n1", 1)]
 
     // #when
-    const next = getNewMessages(sessionID, shorter)
+    const next = consumeNewMessages(sessionID, shorter)
 
     // #then
     expect(next).toEqual(shorter)
@@ -54,11 +54,11 @@ describe("getNewMessages", () => {
   it("returns all messages when last key is missing", () => {
     // #given
     const messages = [buildMessage("m1", 1), buildMessage("m2", 2)]
-    getNewMessages(sessionID, messages)
+    consumeNewMessages(sessionID, messages)
     const replaced = [buildMessage("n1", 1), buildMessage("n2", 2)]
 
     // #when
-    const next = getNewMessages(sessionID, replaced)
+    const next = consumeNewMessages(sessionID, replaced)
 
     // #then
     expect(next).toEqual(replaced)
diff --git a/src/shared/session-cursor.ts b/src/shared/session-cursor.ts
index d9c38a28..37ec0bab 100644
--- a/src/shared/session-cursor.ts
+++ b/src/shared/session-cursor.ts
@@ -40,7 +40,7 @@ function buildMessageKey(message: CursorMessage, index: number): string {
   return `i:${index}`
 }
 
-export function getNewMessages<T extends CursorMessage>(
+export function consumeNewMessages<T extends CursorMessage>(
   sessionID: string | undefined,
   messages: T[]
 ): T[] {
diff --git a/src/tools/background-task/tools.ts b/src/tools/background-task/tools.ts
index 19962e1e..02000931 100644
--- a/src/tools/background-task/tools.ts
+++ b/src/tools/background-task/tools.ts
@@ -7,7 +7,7 @@ import { BACKGROUND_TASK_DESCRIPTION, BACKGROUND_OUTPUT_DESCRIPTION, BACKGROUND_
 import { findNearestMessageWithFields, findFirstMessageWithAgent, MESSAGE_STORAGE } from "../../features/hook-message-injector"
 import { getSessionAgent } from "../../features/claude-code-session-state"
 import { log } from "../../shared/logger"
-import { getNewMessages } from "../../shared/session-cursor"
+import { consumeNewMessages } from "../../shared/session-cursor"
 
 type OpencodeClient = PluginInput["client"]
 
@@ -240,7 +240,7 @@ Session ID: ${task.sessionID}
     return timeA.localeCompare(timeB)
   })
   
-  const newMessages = getNewMessages(task.sessionID, sortedMessages)
+  const newMessages = consumeNewMessages(task.sessionID, sortedMessages)
   if (newMessages.length === 0) {
     const duration = formatDuration(task.startedAt, task.completedAt)
     return `Task Result
diff --git a/src/tools/call-omo-agent/tools.ts b/src/tools/call-omo-agent/tools.ts
index 18e3168f..ef92341c 100644
--- a/src/tools/call-omo-agent/tools.ts
+++ b/src/tools/call-omo-agent/tools.ts
@@ -5,7 +5,7 @@ import { ALLOWED_AGENTS, CALL_OMO_AGENT_DESCRIPTION } from "./constants"
 import type { CallOmoAgentArgs } from "./types"
 import type { BackgroundManager } from "../../features/background-agent"
 import { log } from "../../shared/logger"
-import { getNewMessages } from "../../shared/session-cursor"
+import { consumeNewMessages } from "../../shared/session-cursor"
 import { findFirstMessageWithAgent, findNearestMessageWithFields, MESSAGE_STORAGE } from "../../features/hook-message-injector"
 import { getSessionAgent } from "../../features/claude-code-session-state"
 
@@ -291,7 +291,7 @@ async function executeSync(
     return timeA - timeB
   })
 
-  const newMessages = getNewMessages(sessionID, sortedMessages)
+  const newMessages = consumeNewMessages(sessionID, sortedMessages)
 
   if (newMessages.length === 0) {
     return `No new output since last check.\n\n<task_metadata>\nsession_id: ${sessionID}\n</task_metadata>`