@gajae-code/coding-agent 0.11.1 → 0.11.3

package/src/sdk/bus/threaded-inbound.ts

@@ -63,7 +63,7 @@ export type ThreadedInboundDecision =
 			text: string;
 			updateId: number;
 			threadId: string;
-			messageId?: number;
+			messageId: number;
 			attachment?: InboundAttachment;
 	  }
 	| { kind: "duplicate"; updateId: number }
@@ -118,7 +118,9 @@ export function decideThreadedInbound(update: InboundUpdate, ctx: ThreadedInboun
 	const sessionId = ctx.topicToSession(threadId);
 	if (sessionId === undefined) return { kind: "ignore", reason: "unknown_topic" };
 
-	if (typeof update.update_id !== "number") return { kind: "ignore", reason: "missing_update_id" };
+	if (typeof update.update_id !== "number" || !Number.isSafeInteger(update.update_id) || update.update_id < 0) {
+		return { kind: "ignore", reason: "missing_update_id" };
+	}
 	const updateId = update.update_id;
 	if (ctx.isDuplicate(updateId)) return { kind: "duplicate", updateId };
 
@@ -131,6 +133,9 @@ export function decideThreadedInbound(update: InboundUpdate, ctx: ThreadedInboun
 	const attachment = extractAttachment(message);
 	if (!text && attachment === undefined) return { kind: "ignore", reason: "empty_text" };
 
-	const messageId = typeof message.message_id === "number" ? message.message_id : undefined;
+	if (typeof message.message_id !== "number" || !Number.isSafeInteger(message.message_id) || message.message_id <= 0) {
+		return { kind: "ignore", reason: "missing_message_id" };
+	}
+	const messageId = message.message_id;
 	return { kind: "inject", sessionId, text, updateId, threadId, messageId, attachment };
 }

package/src/sdk/bus/threaded-render.ts

@@ -45,6 +45,13 @@ export interface ThreadedSend {
 	richMarkdown?: string;
 	/** Live-turn raw markdown for opt-in draft streaming (set ONLY on non-finalized turn frames; never triggers rich-final promotion, which requires `lane === "finalized"`). */
 	richDraftMarkdown?: string;
+	/**
+	 * True for a terminal tool_activity frame (phase completed/failed/cancelled/
+	 * unknown). The daemon evicts the tool's `tool:<toolCallId>` live-message entry
+	 * after delivering it, so completed tools do not accumulate unbounded across a
+	 * long session (concurrent in-flight `started` entries are retained).
+	 */
+	terminal?: boolean;
 }
 
 interface ThreadedFrame {
@@ -63,11 +70,18 @@ interface ThreadedFrame {
 	model?: unknown;
 	diff?: unknown;
 	cwd?: unknown;
-	// turn_stream
+	// turn_stream / reasoning_summary
 	phase?: unknown;
 	finalAnswer?: boolean;
 	text?: unknown;
 	messageRef?: unknown;
+	turnRef?: unknown;
+	// tool_activity
+	toolCallId?: unknown;
+	toolName?: unknown;
+	argsSummary?: unknown;
+	resultSummary?: unknown;
+	isError?: unknown;
 	// image_attachment / file_attachment
 	source?: unknown;
 	data?: unknown;
@@ -184,6 +198,48 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 				richDraftMarkdown: finalized ? undefined : raw,
 			};
 		}
+		case "tool_activity": {
+			const toolCallId = str(frame.toolCallId);
+			if (!toolCallId) return undefined;
+			const phase = str(frame.phase);
+			const status =
+				phase === "started"
+					? "started"
+					: phase === "completed" && frame.isError !== true
+						? "ok"
+						: phase === "completed" || phase === "failed"
+							? "error"
+							: phase === "cancelled"
+								? "cancelled"
+								: "unknown";
+			const argsSummary = str(frame.argsSummary);
+			const resultSummary = str(frame.resultSummary);
+			const lines = [`⚙ ${escapeHtml(truncate(str(frame.toolName) ?? "tool", 300))} — ${status}`];
+			if (argsSummary) lines.push(`args:\n${pre(truncate(argsSummary, 1200))}`);
+			if (resultSummary) lines.push(`result:\n${pre(truncate(resultSummary, 1200))}`);
+			return {
+				method: "sendMessage",
+				lane: phase === "started" ? "live" : "finalized",
+				text: finalizeTelegramHtml(lines.join("\n")),
+				coalesceKey: `tool:${toolCallId}`,
+				editable: true,
+				terminal: phase !== "started",
+			};
+		}
+		case "reasoning_summary": {
+			const text = str(frame.text);
+			if (!text) return undefined;
+			const turnRef = str(frame.turnRef);
+			return {
+				method: "sendMessage",
+				lane: "finalized",
+				// markdownToTelegramHtml escapes raw markdown itself; pre-escaping here
+				// would turn entities such as < into visible &amp;lt; text.
+				text: finalizeTelegramHtml(markdownToTelegramHtml(text)),
+				coalesceKey: turnRef ? `reason:${turnRef}` : undefined,
+				editable: turnRef !== undefined,
+			};
+		}
 		case "image_attachment": {
 			const data = str(frame.data);
 			if (!data) return undefined;

package/src/sdk/bus/topic-registry.ts

@@ -21,6 +21,8 @@ export interface TopicRecord {
 	identitySent: boolean;
 	/** Creation timestamp (ms epoch). */
 	createdAt: number;
+	/** First positive observation that the owning endpoint is stale, dead, or missing. */
+	orphanedAt?: number;
 	/** Last applied or observed Telegram topic title. */
 	name?: string;
 	/** Naming authority. Missing values are legacy daemon-owned records. */
@@ -35,12 +37,24 @@ export interface TopicRecord {
 	replayGeneration?: number;
 	/** Last SDK event sequence durably consumed within replayGeneration. */
 	replaySeq?: number;
+	/** Serialized authority epoch; a late create may commit only in its starting epoch. */
+	authorityEpoch?: number;
+	/** An uncertain delete fences future creation and inbound routing. */
+	authorityState?: "active" | "delete_pending";
 }
 
 /** Serialisable shape persisted to disk. */
 export interface TopicRegistryState {
 	/** sessionId -> record. */
 	topics: Record<string, TopicRecord>;
+	/** Durable deletion epochs retained after a definite delete. */
+	fences?: Record<string, number>;
+}
+
+function isValidTopicId(value: unknown): value is string {
+	return (
+		typeof value === "string" && /^[1-9]\d*$/.test(value) && Number.isSafeInteger(Number(value)) && Number(value) > 0
+	);
 }
 
 export function emptyTopicRegistryState(): TopicRegistryState {
@@ -56,8 +70,12 @@ export class TopicRegistry {
 	private readonly topics: Map<string, TopicRecord>;
 	/** Maps topicId -> sessionId for fast inbound routing. */
 	private readonly byTopic = new Map<string, string>();
+	/** Persisted collisions are ambiguous and must never authorize inbound routing. */
+	readonly #ambiguousTopicIds = new Set<string>();
 	/** In-flight create promises, keyed by session, to dedupe concurrent creates. */
 	private readonly inflight = new Map<string, Promise<TopicRecord>>();
+	/** Monotonic authority epochs, including deletion fences for absent records. */
+	private readonly epochs = new Map<string, number>();
 
 	constructor(state: TopicRegistryState = emptyTopicRegistryState()) {
 		this.topics = new Map();
@@ -66,8 +84,12 @@ export class TopicRegistry {
 
 	/** Merge serialized state and normalize authority fields from older releases. */
 	load(state: TopicRegistryState): void {
+		for (const [sessionId, epoch] of Object.entries(state.fences ?? {})) {
+			if (Number.isSafeInteger(epoch) && epoch >= 0) this.epochs.set(sessionId, epoch);
+		}
+
 		for (const [sessionId, raw] of Object.entries(state.topics ?? {})) {
-			if (!raw || typeof raw.topicId !== "string") continue;
+			if (!raw || !isValidTopicId(raw.topicId)) continue;
 			const hasValidUserAuthority =
 				raw.nameOwner === "user" &&
 				typeof raw.name === "string" &&
@@ -87,14 +109,45 @@ export class TopicRegistry {
 				identitySent: raw.identitySent === true,
 				createdAt: typeof raw.createdAt === "number" ? raw.createdAt : 0,
 				...(typeof raw.name === "string" ? { name: raw.name } : {}),
+				...(typeof raw.orphanedAt === "number" && Number.isFinite(raw.orphanedAt) && raw.orphanedAt >= 0
+					? { orphanedAt: raw.orphanedAt }
+					: {}),
 				...(hasValidUserAuthority ? { nameOwner: "user" as const } : {}),
 				...(hasValidUserAuthority && raw.nameReconcilePending === true ? { nameReconcilePending: true } : {}),
 				...(hasValidUserAuthority ? { userNameUpdateId: raw.userNameUpdateId } : {}),
 				...(typeof raw.identityKey === "string" ? { identityKey: raw.identityKey } : {}),
 				...(hasValidReplayCursor ? { replayGeneration: raw.replayGeneration, replaySeq: raw.replaySeq } : {}),
+				...(Number.isSafeInteger(raw.authorityEpoch) && raw.authorityEpoch! >= 0
+					? { authorityEpoch: raw.authorityEpoch }
+					: {}),
+				...(raw.authorityState === "delete_pending" ? { authorityState: "delete_pending" as const } : {}),
 			};
+			this.epochs.set(sessionId, Math.max(this.epochs.get(sessionId) ?? 0, record.authorityEpoch ?? 0));
+
 			this.topics.set(sessionId, record);
-			this.byTopic.set(record.topicId, sessionId);
+		}
+		this.rebuildInboundRoutes();
+	}
+
+	private rebuildInboundRoutes(): void {
+		this.byTopic.clear();
+		this.#ambiguousTopicIds.clear();
+		const activeByTopic = new Map<string, string>();
+
+		for (const [sessionId, record] of this.topics) {
+			if (record.authorityState === "delete_pending") {
+				this.#ambiguousTopicIds.add(record.topicId);
+				continue;
+			}
+			if (activeByTopic.has(record.topicId)) {
+				this.#ambiguousTopicIds.add(record.topicId);
+				continue;
+			}
+			activeByTopic.set(record.topicId, sessionId);
+		}
+
+		for (const [topicId, sessionId] of activeByTopic) {
+			if (!this.#ambiguousTopicIds.has(topicId)) this.byTopic.set(topicId, sessionId);
 		}
 	}
 
@@ -119,22 +172,36 @@ export class TopicRegistry {
 	 */
 	async getOrCreateTopic(
 		sessionId: string,
-		create: () => Promise<string>,
+		create: () => Promise<unknown>,
 		now: () => number = Date.now,
 		name?: string,
 	): Promise<TopicRecord> {
 		const existing = this.topics.get(sessionId);
+		if (existing?.authorityState === "delete_pending") throw new Error("topic authority is deletion-fenced");
 		if (existing) return existing;
-		// Concurrency guard: many session frames (identity/idle/turn/ask) can race
-		// to first-use the same session. Without this, each call passes the
-		// `existing` check before `create()` resolves and creates a DUPLICATE
-		// forum topic. Share a single in-flight create per session id.
 		const pending = this.inflight.get(sessionId);
 		if (pending) return pending;
+		const epoch = this.epochs.get(sessionId) ?? 0;
 		const promise = (async () => {
 			const topicId = await create();
-			const record: TopicRecord = { topicId, name, identitySent: false, createdAt: now() };
+			if (!isValidTopicId(topicId)) throw new Error("createForumTopic: invalid message_thread_id");
+			const revoked = (this.epochs.get(sessionId) ?? 0) !== epoch;
+			const record: TopicRecord = {
+				topicId,
+				name,
+				identitySent: false,
+				createdAt: now(),
+				authorityEpoch: revoked ? (this.epochs.get(sessionId) ?? 0) : epoch,
+				...(revoked ? { authorityState: "delete_pending" as const } : {}),
+			};
 			this.topics.set(sessionId, record);
+			if (revoked) throw new Error("topic authority was revoked during creation");
+			if (this.#ambiguousTopicIds.has(topicId)) return record;
+			if (this.byTopic.has(topicId)) {
+				this.byTopic.delete(topicId);
+				this.#ambiguousTopicIds.add(topicId);
+				return record;
+			}
 			this.byTopic.set(topicId, sessionId);
 			return record;
 		})();
@@ -165,6 +232,21 @@ export class TopicRegistry {
 		record.identityKey = identityKey;
 		return true;
 	}
+	/** Start the orphan grace clock on the first positive liveness-loss observation. */
+	markOrphaned(sessionId: string, now: number): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.orphanedAt !== undefined) return false;
+		record.orphanedAt = now;
+		return true;
+	}
+
+	/** Clear a prior orphan observation after the endpoint is positively live again. */
+	clearOrphaned(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.orphanedAt === undefined) return false;
+		delete record.orphanedAt;
+		return true;
+	}
 
 	/** Last durably consumed SDK event cursor for reconnect replay. */
 	replayCursor(sessionId: string): { generation: number; seq: number } | undefined {
@@ -241,17 +323,42 @@ export class TopicRegistry {
 		record.nameReconcilePending = false;
 	}
 
-	/** Remove a session topic record after Telegram deletes the topic. */
-	delete(sessionId: string): boolean {
+	/** Fence new work before the remote delete starts, including an absent in-flight create. */
+	beginDelete(sessionId: string): TopicRecord | undefined {
 		const record = this.topics.get(sessionId);
-		if (!record) return false;
+		const epoch = Math.max(this.epochs.get(sessionId) ?? 0, record?.authorityEpoch ?? 0) + 1;
+		this.epochs.set(sessionId, epoch);
+		if (!record) return undefined;
+		record.authorityEpoch = epoch;
+		record.authorityState = "delete_pending";
+		if (this.byTopic.get(record.topicId) === sessionId) this.byTopic.delete(record.topicId);
+		return record;
+	}
+
+	/** Wait for a revoked create to settle before admitting a later lifecycle epoch. */
+	async awaitInflight(sessionId: string): Promise<void> {
+		await this.inflight.get(sessionId)?.catch(() => undefined);
+	}
+
+	/** Remove only after a definite remote deletion; ambiguity deliberately retains its fence. */
+	settleDelete(sessionId: string, topicId: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.topicId !== topicId || record.authorityState !== "delete_pending") return false;
 		this.topics.delete(sessionId);
-		this.byTopic.delete(record.topicId);
 		return true;
 	}
 
+	/** Remove a topic record immediately for local/test cleanup compatibility. */
+	delete(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record) return false;
+		this.epochs.set(sessionId, Math.max(this.epochs.get(sessionId) ?? 0, record.authorityEpoch ?? 0) + 1);
+		if (this.byTopic.get(record.topicId) === sessionId) this.byTopic.delete(record.topicId);
+		return this.topics.delete(sessionId);
+	}
+
 	/** Serialise for atomic persistence beside the daemon state. */
 	serialize(): TopicRegistryState {
-		return { topics: Object.fromEntries(this.topics) };
+		return { topics: Object.fromEntries(this.topics), fences: Object.fromEntries(this.epochs) };
 	}
 }

package/src/sdk/host/control/dispatch.ts

@@ -133,6 +133,7 @@ function invoke(
 	operation: string,
 	input: ControlInput,
 	confirm: boolean | undefined,
+	idempotencyKey: string | undefined,
 ): Promise<ControlValue> | ControlValue {
 	switch (operation) {
 		case "turn.prompt":
@@ -148,7 +149,12 @@ function invoke(
 		case "ask.answer":
 			return surface.answerAsk(text(input, "id"), input.answer);
 		case "workflow.gate_answer":
-			return surface.answerGate(text(input, "id"), input.response, input.expectedSessionId as string | undefined);
+			return surface.answerGate(
+				text(input, "id"),
+				input.response,
+				input.expectedSessionId as string | undefined,
+				idempotencyKey,
+			);
 		case "workflow.plan_approve":
 			return surface.approvePlan(text(input, "id"), input.choice, input.expectedSessionId as string | undefined);
 		case "skill.invoke":
@@ -276,7 +282,13 @@ async function execute(surface: ControlSurface, row: Operation, request: Control
 		return {
 			id: request.id,
 			ok: true,
-			result: await invoke(surface, row.sdkId, request.input as ControlInput, request.confirm),
+			result: await invoke(
+				surface,
+				row.sdkId,
+				request.input as ControlInput,
+				request.confirm,
+				request.idempotencyKey,
+			),
 		};
 	} catch (error) {
 		return errorResponse(request.id, row, error);

package/src/sdk/host/control/operations.ts

@@ -12,7 +12,12 @@ export interface ControlSurface {
 	abort(): Promise<ControlValue> | ControlValue;
 	abortAndPrompt(text: string): Promise<ControlValue> | ControlValue;
 	answerAsk(id: string, answer: ControlValue): Promise<ControlValue> | ControlValue;
-	answerGate(id: string, response: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
+	answerGate(
+		id: string,
+		response: ControlValue,
+		expectedSessionId?: string,
+		idempotencyKey?: string,
+	): Promise<ControlValue> | ControlValue;
 	approvePlan(id: string, choice: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
 	invokeSkill(name: string, args: ControlValue): Promise<ControlValue> | ControlValue;
 	setPlanMode(on: boolean): Promise<ControlValue> | ControlValue;

package/src/sdk/host/host.ts

@@ -14,8 +14,14 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	installProviderDefinitions?: (capability: string, definitions: unknown) => void;
 	onProviderDefinitionsRemoved?: (capability: string) => void;
 	onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
+	/** Best-effort capabilities mirrored from the native transport for out-of-band consumers. */
+	connectionCapabilities?: (connectionId: string) => ReadonlySet<string>;
 }
 
+const TOOL_ACTIVITY_V1 = "tool_activity_v1";
+const CAP_GATED_FRAME_KINDS = new Set(["tool_activity", "reasoning_summary"]);
+const EMPTY_CAPABILITIES: ReadonlySet<string> = new Set();
+
 /** SDK hosting is independent of notification configuration. Only root sessions host an endpoint. */
 export function shouldHostSdk(_settings: unknown, isTopLevel: boolean, env: NodeJS.ProcessEnv = process.env): boolean {
 	return isTopLevel && env.GJC_SDK_DISABLE !== "1";
@@ -96,6 +102,7 @@ export class SessionSdkHost {
 	readonly reverse: ReverseLeaseRuntime;
 	readonly #options: SessionSdkHostOptions;
 	#started = false;
+	#stopPromise?: Promise<"stopped">;
 	#unsubscribe?: () => void;
 	#registration?: { writer: BrokerIndexWriter; generation: number };
 
@@ -148,16 +155,27 @@ export class SessionSdkHost {
 	}
 
 	async stop(): Promise<"stopped" | "already"> {
+		if (this.#stopPromise) return this.#stopPromise;
 		if (!this.#started) return "already";
+		const stopPromise = this.#stopStartedHost();
+		this.#stopPromise = stopPromise;
+		try {
+			return await stopPromise;
+		} finally {
+			if (this.#stopPromise === stopPromise) this.#stopPromise = undefined;
+		}
+	}
+
+	async #stopStartedHost(): Promise<"stopped"> {
 		this.#unsubscribe?.();
 		this.#unsubscribe = undefined;
-		this.#started = false;
 		if (this.#registration?.writer.unregister)
 			await this.#registration.writer.unregister({
 				sessionId: this.#options.sessionId,
 				stateRoot: this.#options.stateRoot,
 				endpointGeneration: this.events.generation,
 			});
+		this.#started = false;
 		return "stopped";
 	}
 
@@ -175,6 +193,19 @@ export class SessionSdkHost {
 		await this.#options.sendFrame(connectionId, frame);
 	}
 
+	/**
+	 * Best-effort delivery for structured error frames. When the original failure
+	 * was already a disconnected/dead connection, a second send must not escape
+	 * the fire-and-forget `#onFrame` callback as an unhandled rejection.
+	 */
+	async #sendBestEffort(connectionId: string, frame: SdkFrame): Promise<void> {
+		try {
+			await this.#send(connectionId, frame);
+		} catch {
+			// Per-connection delivery only; never rethrow into fire-and-forget handlers.
+		}
+	}
+
 	async #onFrame(connectionId: string, frame: SdkFrame): Promise<void> {
 		try {
 			switch (frame.type) {
@@ -200,11 +231,20 @@ export class SessionSdkHost {
 					const sinceGeneration = rawGeneration;
 					const sinceSeq = rawSeq;
 					const replay = this.events.replay(sinceSeq, sinceGeneration);
+					const capabilities = Array.isArray(frame.capabilities)
+						? new Set(
+								frame.capabilities.filter((capability): capability is string => typeof capability === "string"),
+							)
+						: (this.#options.connectionCapabilities?.(connectionId) ?? EMPTY_CAPABILITIES);
+					const events = replay.events.filter(
+						event => !CAP_GATED_FRAME_KINDS.has(String(event.kind)) || capabilities.has(TOOL_ACTIVITY_V1),
+					);
 					await this.#send(connectionId, {
 						type: "event_replay_result",
 						id,
 						ok: true,
 						...replay,
+						events,
 						generation: this.events.generation,
 						lastSeq: this.events.sequence,
 					});
@@ -283,7 +323,9 @@ export class SessionSdkHost {
 					return;
 			}
 		} catch (error) {
-			await this.#send(connectionId, errorFrame(connectionId, frame, error));
+			// Structured error delivery is best-effort: if the client already
+			// disconnected, do not escalate a second send failure process-wide.
+			await this.#sendBestEffort(connectionId, errorFrame(connectionId, frame, error));
 		}
 	}
 	#observeRequest(kind: "control" | "query", connectionId: string, frame: SdkFrame): void {

package/src/sdk/host/query/handlers.ts

@@ -378,31 +378,24 @@ export class QueryHandlers {
 		const input = request.input ?? {};
 		const artifactId = String(input.artifactId ?? "");
 		const start = Math.max(0, Number(input.offset ?? 0));
-		const maxRawBytes = Math.floor(((RESPONSE_CEILING_BYTES - 4096) * 3) / 4);
+		const emptyResult = { artifactId, offset: start, bytes: "", complete: false };
+		const baseBytes = Buffer.byteLength(JSON.stringify({ id: request.id, ok: true, result: emptyResult }));
+		const maxRawBytes = Math.floor((RESPONSE_CEILING_BYTES - baseBytes) / 4) * 3;
 		const requested = Math.max(0, Math.min(Number(input.length ?? TARGET_PAGE_BYTES), maxRawBytes));
 		const artifact = await this.surface.getArtifactRange?.(artifactId, start, requested);
 		if (!artifact) return this.#error(request, "resource_gone");
-		let bytes = Buffer.from(artifact.bytes);
-		let result = {
-			artifactId,
-			offset: start,
-			bytes: bytes.toString("base64"),
-			complete: start + bytes.length >= artifact.totalBytes,
-		};
-		while (
-			Buffer.byteLength(JSON.stringify({ id: request.id, ok: true, result })) >= RESPONSE_CEILING_BYTES &&
-			bytes.length > 0
-		) {
-			bytes = bytes.subarray(0, bytes.length - Math.max(1, Math.ceil(bytes.length / 128)));
-			result = {
+		const bytes = Buffer.from(artifact.bytes);
+		if (bytes.length === 0 && start < artifact.totalBytes) return this.#error(request, "item_too_large");
+		return {
+			id: request.id,
+			ok: true,
+			result: {
 				artifactId,
 				offset: start,
 				bytes: bytes.toString("base64"),
 				complete: start + bytes.length >= artifact.totalBytes,
-			};
-		}
-		if (bytes.length === 0 && start < artifact.totalBytes) return this.#error(request, "item_too_large");
-		return { id: request.id, ok: true, result };
+			},
+		};
 	}
 
 	async #paginate(
@@ -417,12 +410,17 @@ export class QueryHandlers {
 	): Promise<QueryResponse> {
 		const values = Array.isArray(snapshot) ? snapshot : [snapshot];
 		const items: unknown[] = [];
+		let itemsBytes = 2; // []
 		let index = offset;
 		while (index < values.length) {
-			const candidate = [...items, values[index]];
-			if (Buffer.byteLength(JSON.stringify(candidate)) > TARGET_PAGE_BYTES && items.length) break;
-			if (Buffer.byteLength(JSON.stringify(candidate)) > RESPONSE_CEILING_BYTES) break;
-			items.push(values[index++]);
+			const item = values[index]!;
+			const itemBytes = Buffer.byteLength(JSON.stringify(item) ?? "null");
+			const candidateBytes = itemsBytes + itemBytes + (items.length ? 1 : 0);
+			if (candidateBytes > TARGET_PAGE_BYTES && items.length) break;
+			if (candidateBytes > RESPONSE_CEILING_BYTES) break;
+			items.push(item);
+			itemsBytes = candidateBytes;
+			index++;
 		}
 		const complete = index >= values.length;
 		const page: QueryPage = { items, complete, revision };