docs(agent): clarify branch query helpers

This commit is contained in:
Vegard Stikbakke 2026-08-07 09:55:13 +02:00
parent 80ef7ff0f4
commit f562a1a44f

View file

@ -223,6 +223,7 @@ export class Session<TMetadata extends SessionMetadata = SessionMetadata> implem
return this.queryLog(options);
}
/** Returns the lane's current leaf, or null when empty. Throws when the lane does not exist. */
private async getLeafIdForLane(lane: string): Promise<string | null> {
const pointer = (await this.getLanes()).find((candidate) => candidate.lane === lane);
if (!pointer) throw new SessionError("invalid_lane", `Lane not found: ${lane}`);
@ -235,14 +236,18 @@ export class Session<TMetadata extends SessionMetadata = SessionMetadata> implem
return this.storage.findEntries(resultLimit === query.limit ? query : { ...query, limit: resultLimit });
}
/**
* Queries from `query.start` toward the root, defaulting to the lane's current leaf.
* `resultLimit` lets single-entry queries cap results without changing the caller's query.
*/
private async queryBranchEntries(
lane: string,
defaultLane: string,
query: EntryQuery & BranchBounds = {},
resultLimit = query.limit,
): Promise<Entry[]> {
assertValidLimit(query.limit);
assertValidCursor(query.cursor?.afterSeq);
const start = query.start ?? (await this.getLeafIdForLane(lane));
const start = query.start ?? (await this.getLeafIdForLane(defaultLane));
if (start === null) return [];
const storageQuery = resultLimit === query.limit ? query : { ...query, limit: resultLimit };
return this.storage.findEntriesOnBranch({ ...storageQuery, start });