Skip to content

Commit dc575d1

Browse files
galinilievgaliniliev
authored
fix: page sessions_history beyond truncated tails (#97101)
* Add sessions history offset pagination * Fix sessions_history pagination after tool caps * Fix sessions_history PR CI blockers * Update sessions_history prompt snapshots * Fix offset history projection windows --------- Co-authored-by: Galin Iliev <[email protected]>
1 parent 12685ee commit dc575d1

23 files changed

Lines changed: 1257 additions & 103 deletions

‎apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7187,24 +7187,28 @@ public struct ChatHistoryParams: Codable, Sendable {
71877187
public let sessionkey: String
71887188
public let agentid: String?
71897189
public let limit: Int?
7190+
public let offset: Int?
71907191
public let maxchars: Int?
71917192

71927193
public init(
71937194
sessionkey: String,
71947195
agentid: String? = nil,
71957196
limit: Int?,
7197+
offset: Int? = nil,
71967198
maxchars: Int?)
71977199
{
71987200
self.sessionkey = sessionkey
71997201
self.agentid = agentid
72007202
self.limit = limit
7203+
self.offset = offset
72017204
self.maxchars = maxchars
72027205
}
72037206

72047207
private enum CodingKeys: String, CodingKey {
72057208
case sessionkey = "sessionKey"
72067209
case agentid = "agentId"
72077210
case limit
7211+
case offset
72087212
case maxchars = "maxChars"
72097213
}
72107214
}

‎docs/concepts/delegate-architecture.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -297,7 +297,8 @@ tool-call XML payloads (including `<tool_call>...</tool_call>`,
297297
downgraded tool-call scaffolding / leaked ASCII/full-width model control
298298
tokens / malformed MiniMax tool-call XML from assistant recall, and can
299299
replace oversized rows with `[sessions_history omitted: message too large]`
300-
instead of returning a raw transcript dump.
300+
instead of returning a raw transcript dump. Use `nextOffset` when present to
301+
page backward through older transcript windows.
301302

302303
## Scaling pattern
303304

‎docs/concepts/session-tool.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,11 @@ results may be scope-limited.
5858

5959
`sessions_history` fetches the conversation transcript for a specific session.
6060
By default, tool results are excluded -- pass `includeTools: true` to see them.
61+
Use `limit` for the newest bounded tail. Pass `offset: 0` when you need
62+
pagination metadata, then pass returned `nextOffset` values to page backward
63+
through older OpenClaw transcript windows without reading raw transcript files.
64+
Explicit offset pages do not merge external CLI fallback imports; use the
65+
default newest-tail view when you need that merged display history.
6166
The returned view is intentionally bounded and safety-filtered:
6267

6368
- assistant text is normalized before recall:
@@ -78,7 +83,7 @@ The returned view is intentionally bounded and safety-filtered:
7883
- very large histories can drop older rows or replace an oversized row with
7984
`[sessions_history omitted: message too large]`
8085
- the tool reports summary flags such as `truncated`, `droppedMessages`,
81-
`contentTruncated`, `contentRedacted`, and `bytes`
86+
`contentTruncated`, `contentRedacted`, `bytes`, and pagination metadata
8287

8388
Both tools accept either a **session key** (like `"main"`) or a **session ID**
8489
from a previous list call.

‎docs/tools/subagents.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -523,6 +523,7 @@ should be rewritten in normal assistant voice.
523523
- Credential/token-like text is redacted.
524524
- Long blocks can be truncated.
525525
- Very large histories can drop older rows or replace an oversized row with `[sessions_history omitted: message too large]`.
526+
- Use `nextOffset` when present to page backward through older transcript windows.
526527
- Raw on-disk transcript inspection is the fallback when you need the full byte-for-byte transcript.
527528

528529
## Tool policy

‎packages/gateway-protocol/src/index.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ describe("lazy protocol validators", () => {
9191
sessionKey: "global",
9292
agentId: "work",
9393
limit: 50,
94+
offset: 100,
9495
}),
9596
).toBe(true);
9697
expect(

‎packages/gateway-protocol/src/schema/logs-chat.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ export const ChatHistoryParamsSchema = Type.Object(
3232
sessionKey: NonEmptyString,
3333
agentId: Type.Optional(NonEmptyString),
3434
limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 1000 })),
35+
offset: Type.Optional(Type.Integer({ minimum: 0 })),
3536
maxChars: Type.Optional(Type.Integer({ minimum: 1, maximum: 500_000 })),
3637
},
3738
{ additionalProperties: false },

‎scripts/protocol-gen-swift.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ const DEFAULTED_OPTIONAL_INIT_PARAM_ENTRIES: readonly [string, readonly string[]
5858
["SessionsCompactParams", ["agentId"]],
5959
["SessionsResolveParams", ["allowMissing"]],
6060
["SessionsUsageParams", ["agentId", "agentScope"]],
61-
["ChatHistoryParams", ["agentId"]],
61+
["ChatHistoryParams", ["agentId", "offset"]],
6262
["ChatSendParams", ["agentId"]],
6363
["ChatAbortParams", ["agentId"]],
6464
["ChatInjectParams", ["agentId"]],
@@ -74,7 +74,7 @@ const DEFAULTED_OPTIONAL_INIT_PARAM_ENTRIES: readonly [string, readonly string[]
7474
["ChatDeltaEvent", ["agentId"]],
7575
["ChatErrorEvent", ["agentId"]],
7676
["ChatFinalEvent", ["agentId"]],
77-
["ChatHistoryParams", ["agentId"]],
77+
["ChatHistoryParams", ["agentId", "offset"]],
7878
["ChatInjectParams", ["agentId"]],
7979
["ChatSendParams", ["agentId"]],
8080
["MessageActionParams", ["inboundTurnKind", "requesterAccountId"]],

‎src/agents/tool-description-presets.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ export function describeSessionsListTool(): string {
2323
export function describeSessionsHistoryTool(): string {
2424
return [
2525
"Fetch sanitized history for visible session.",
26-
"Use before replying, debugging, resuming; supports limits/tool messages.",
26+
"Use before replying, debugging, resuming; supports limit, offset pagination, and tool-message inclusion.",
2727
].join(" ");
2828
}
2929

‎src/agents/tools/embedded-gateway-stub.runtime.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
export { resolveSessionAgentId } from "../../agents/agent-scope.js";
88
export { getRuntimeConfig } from "../../config/config.js";
99
export {
10+
dropPreSessionStartAnnouncePairs,
11+
projectChatDisplayMessages,
1012
projectRecentChatDisplayMessages,
1113
resolveEffectiveChatHistoryMaxChars,
1214
} from "../../gateway/chat-display-projection.js";
@@ -20,6 +22,8 @@ export {
2022
} from "../../gateway/server-methods/chat.js";
2123
export {
2224
capArrayByJsonBytes,
25+
readRecentSessionMessagesWithStatsAsync,
26+
readSessionMessagesPageWithStatsAsync,
2327
readSessionMessagesAsync,
2428
} from "../../gateway/session-transcript-readers.js";
2529
export {

0 commit comments

Comments
 (0)