Add structured log cursor reads

Author: Joshua

plugin/addons/godot_ai/utils/editor_log_buffer.gd

@@ -66,6 +66,15 @@ func get_recent(count: int) -> Array[Dictionary]:
 	return out
 
 
+func get_since(since_seq: int, limit: int = -1) -> Dictionary:
+	## Single-lock so the cursor snapshot and slice copy can't race against a
+	## Logger-thread append.
+	_mutex.lock()
+	var out := _get_since_unlocked(since_seq, limit)
+	_mutex.unlock()
+	return out
+
+
 func total_count() -> int:
 	_mutex.lock()
 	var n := _total_count_unlocked()
@@ -80,6 +89,13 @@ func dropped_count() -> int:
 	return n
 
 
+func appended_total() -> int:
+	_mutex.lock()
+	var n := _appended_total_unlocked()
+	_mutex.unlock()
+	return n
+
+
 func clear() -> int:
 	_mutex.lock()
 	var n := _total_count_unlocked()

plugin/addons/godot_ai/utils/structured_log_ring.gd

@@ -30,6 +30,10 @@ var _storage: Array[Dictionary] = []
 ## (the one about to be overwritten).
 var _head := 0
 var _dropped_count := 0
+## Monotonic number of entries appended since this ring was created. Unlike
+## `_storage.size()` and `_dropped_count`, this intentionally survives clear()
+## so callers can use it as a stable "next entry to read" cursor.
+var _appended_total := 0
 
 
 func _init(max_lines: int) -> void:
@@ -42,11 +46,12 @@ func _append_entry(entry: Dictionary) -> void:
 	if _storage.size() < _max_lines:
 		_storage.append(entry)
 		_head = _storage.size() % _max_lines
-		return
-	## Full — overwrite oldest in place, advance head, count the drop.
-	_storage[_head] = entry
-	_head = (_head + 1) % _max_lines
-	_dropped_count += 1
+	else:
+		## Full — overwrite oldest in place, advance head, count the drop.
+		_storage[_head] = entry
+		_head = (_head + 1) % _max_lines
+		_dropped_count += 1
+	_appended_total += 1
 
 
 ## Lockless slice. Subclasses with a mutex wrap their `get_range` /
@@ -72,6 +77,34 @@ func get_recent(count: int) -> Array[Dictionary]:
 	return _get_range_unlocked(start, size - start)
 
 
+## Lockless cursor read. The cursor is the next sequence to read: calling
+## get_since(appended_total()) after a snapshot returns only later appends.
+func _get_since_unlocked(since_seq: int, limit: int = -1) -> Dictionary:
+	var size := _storage.size()
+	var oldest_seq := _appended_total - size
+	var start_seq := mini(maxi(since_seq, oldest_seq), _appended_total)
+	var start := start_seq - oldest_seq
+	var available := maxi(0, size - start)
+	var count := available
+	if limit >= 0:
+		count = mini(available, limit)
+	var entries := _get_range_unlocked(start, count)
+	var next_cursor := start_seq + entries.size()
+	return {
+		"cursor": since_seq,
+		"oldest_cursor": oldest_seq,
+		"next_cursor": next_cursor,
+		"appended_total": _appended_total,
+		"truncated": since_seq < oldest_seq,
+		"has_more": next_cursor < _appended_total,
+		"entries": entries,
+	}
+
+
+func get_since(since_seq: int, limit: int = -1) -> Dictionary:
+	return _get_since_unlocked(since_seq, limit)
+
+
 ## Lockless accessors. Subclasses with a mutex use these under their lock
 ## so the field reads stay encapsulated in the base instead of leaking
 ## `_storage` / `_dropped_count` reach-through into the subclass.
@@ -83,6 +116,10 @@ func _dropped_count_unlocked() -> int:
 	return _dropped_count
 
 
+func _appended_total_unlocked() -> int:
+	return _appended_total
+
+
 func total_count() -> int:
 	return _total_count_unlocked()
 
@@ -91,6 +128,10 @@ func dropped_count() -> int:
 	return _dropped_count_unlocked()
 
 
+func appended_total() -> int:
+	return _appended_total_unlocked()
+
+
 ## Translate a logical index (0 = oldest retained) to a physical
 ## `_storage` slot. Before the first wrap, storage-order is logical-
 ## order. After wrapping, the oldest entry lives at `_head`.

test_project/tests/test_editor.gd

@@ -1011,19 +1011,102 @@ func test_editor_log_buffer_ring_evicts_and_tracks_dropped() -> void:
 		buf.append("error", "n %d" % i, "res://x.gd", i)
 	assert_eq(buf.total_count(), cap, "Buffer should cap at MAX_LINES")
 	assert_eq(buf.dropped_count(), 7, "Should record 7 evictions")
+	assert_eq(buf.appended_total(), cap + 7, "Cursor should advance for every append")
 	## Oldest 7 dropped: first remaining entry should be index 7.
 	var first := buf.get_range(0, 1)
 	assert_eq(first[0].text, "n 7")
 
 
+func test_editor_log_buffer_get_since_returns_entries_after_cursor() -> void:
+	var buf := McpEditorLogBuffer.new()
+	buf.append("error", "before-a", "res://a.gd", 1)
+	buf.append("error", "before-b", "res://b.gd", 2)
+	var cursor := buf.appended_total()
+	buf.append("error", "after-a", "res://a.gd", 3)
+	buf.append("warn", "after-b", "res://b.gd", 4)
+
+	var result := buf.get_since(cursor)
+	assert_eq(result.cursor, cursor)
+	assert_eq(result.entries.size(), 2)
+	assert_eq(result.entries[0].text, "after-a")
+	assert_eq(result.entries[1].text, "after-b")
+	assert_eq(result.next_cursor, buf.appended_total())
+	assert_false(result.truncated)
+	assert_false(result.has_more)
+
+
+func test_editor_log_buffer_get_since_reports_overflow_truncation() -> void:
+	var buf := McpEditorLogBuffer.new()
+	var cap := McpEditorLogBuffer.MAX_LINES
+	var cursor := buf.appended_total()
+	for i in range(cap + 3):
+		buf.append("error", "storm %d" % i, "res://storm.gd", i)
+
+	var result := buf.get_since(cursor)
+	assert_true(result.truncated, "Overflow after the cursor must be visible")
+	assert_eq(result.entries.size(), cap)
+	assert_eq(result.entries[0].text, "storm 3")
+	assert_eq(result.entries[cap - 1].text, "storm %d" % (cap + 2))
+	assert_eq(result.oldest_cursor, 3)
+	assert_eq(result.next_cursor, buf.appended_total())
+
+
+func test_editor_log_buffer_get_since_limit_paginates_without_losing_cursor() -> void:
+	var buf := McpEditorLogBuffer.new()
+	for i in range(5):
+		buf.append("error", "page %d" % i)
+
+	var first := buf.get_since(0, 2)
+	assert_eq(first.entries.size(), 2)
+	assert_eq(first.entries[0].text, "page 0")
+	assert_eq(first.next_cursor, 2)
+	assert_true(first.has_more)
+
+	var second := buf.get_since(first.next_cursor, 10)
+	assert_eq(second.entries.size(), 3)
+	assert_eq(second.entries[0].text, "page 2")
+	assert_eq(second.next_cursor, 5)
+	assert_false(second.has_more)
+
+
+func test_editor_log_buffer_get_since_future_cursor_clamps_to_tail() -> void:
+	var buf := McpEditorLogBuffer.new()
+	for i in range(3):
+		buf.append("error", "future %d" % i)
+
+	var result := buf.get_since(99)
+	assert_false(result.truncated)
+	assert_eq(result.entries.size(), 0)
+	assert_eq(result.next_cursor, buf.appended_total())
+	assert_false(result.has_more)
+
+
 func test_editor_log_buffer_clear_resets_counts() -> void:
 	var buf := McpEditorLogBuffer.new()
 	for i in range(5):
 		buf.append("error", "n %d" % i)
+	var cursor := buf.appended_total()
 	var cleared := buf.clear()
 	assert_eq(cleared, 5, "clear() should report cleared count")
 	assert_eq(buf.total_count(), 0)
 	assert_eq(buf.dropped_count(), 0)
+	assert_eq(buf.appended_total(), cursor, "clear() must not reset the cursor")
+
+
+func test_editor_log_buffer_get_since_reports_clear_truncation() -> void:
+	var buf := McpEditorLogBuffer.new()
+	for i in range(5):
+		buf.append("error", "before-clear %d" % i)
+	var stale_cursor := 2
+	buf.clear()
+	buf.append("error", "after-clear", "res://after.gd", 9)
+
+	var result := buf.get_since(stale_cursor)
+	assert_true(result.truncated, "Clear after the cursor should degrade the window")
+	assert_eq(result.entries.size(), 1)
+	assert_eq(result.entries[0].text, "after-clear")
+	assert_eq(result.oldest_cursor, 5)
+	assert_eq(result.next_cursor, 6)
 
 
 # ----- get_logs source="editor" routing (issue #231) -----