@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/sdk/session-list.ts

@@ -0,0 +1,93 @@
+export type SessionListPageRecord = Record<string, unknown>;
+
+export type SessionListTraversalErrorKind = "malformed_page" | "repeated_cursor" | "page_budget_exceeded";
+
+export class SessionListTraversalError extends Error {
+	readonly #kind: SessionListTraversalErrorKind;
+
+	constructor(kind: SessionListTraversalErrorKind) {
+		super(
+			kind === "malformed_page"
+				? "session.list returned a malformed page."
+				: kind === "repeated_cursor"
+					? "session.list returned a repeated continuation cursor."
+					: "session.list exceeded the page budget.",
+		);
+		this.name = "SessionListTraversalError";
+		this.#kind = kind;
+	}
+
+	get kind(): SessionListTraversalErrorKind {
+		return this.#kind;
+	}
+}
+
+export interface SessionListTraversalInputPage {
+	readonly sessions: readonly unknown[];
+	readonly continuationCursor?: unknown;
+}
+
+export interface SessionListTraversalPage<TResponse, TPage extends SessionListTraversalInputPage> {
+	readonly response: TResponse;
+	readonly page: TPage;
+	readonly sessions: readonly unknown[];
+	readonly continuationCursor?: string;
+}
+
+const MAX_SESSION_LIST_PAGES = 10_000;
+
+function record(value: unknown): SessionListPageRecord | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as SessionListPageRecord)
+		: undefined;
+}
+
+export type SessionListPage = SessionListPageRecord & SessionListTraversalInputPage;
+
+/** Returns a strict session.list page from either a Broker envelope or a direct result record. */
+export function sessionListPageFromResponse(value: unknown): SessionListPage | undefined {
+	const response = record(value);
+	if (!response) return undefined;
+	const page = Object.hasOwn(response, "ok") ? (response.ok === true ? record(response.result) : undefined) : response;
+	if (!page || !Array.isArray(page.sessions)) return undefined;
+	return page as SessionListPage;
+}
+
+/** Drains bounded Broker session.list pages while rejecting malformed or cyclic continuations. */
+export async function traverseSessionList<
+	TInput extends Record<string, unknown>,
+	TResponse,
+	TPage extends SessionListTraversalInputPage,
+>(
+	input: TInput,
+	request: (input: TInput) => Promise<TResponse>,
+	pageFromResponse: (response: TResponse) => TPage | undefined,
+): Promise<readonly SessionListTraversalPage<TResponse, TPage>[]> {
+	const pages: SessionListTraversalPage<TResponse, TPage>[] = [];
+	const seenCursors = new Set<string>();
+	const initialCursor = input.cursor;
+	if (typeof initialCursor === "string" && initialCursor.length > 0) seenCursors.add(initialCursor);
+	let cursor: string | undefined;
+	for (let pageCount = 0; pageCount < MAX_SESSION_LIST_PAGES; pageCount++) {
+		const response = await request({ ...input, ...(cursor === undefined ? {} : { cursor }) } as TInput);
+		const page = pageFromResponse(response);
+		if (!page || !Array.isArray(page.sessions)) throw new SessionListTraversalError("malformed_page");
+		const continuationCursor = page.continuationCursor;
+		if (
+			continuationCursor !== undefined &&
+			(typeof continuationCursor !== "string" || continuationCursor.length === 0)
+		)
+			throw new SessionListTraversalError("malformed_page");
+		pages.push({
+			response,
+			page,
+			sessions: page.sessions,
+			...(continuationCursor === undefined ? {} : { continuationCursor }),
+		});
+		if (continuationCursor === undefined) return pages;
+		if (seenCursors.has(continuationCursor)) throw new SessionListTraversalError("repeated_cursor");
+		seenCursors.add(continuationCursor);
+		cursor = continuationCursor;
+	}
+	throw new SessionListTraversalError("page_budget_exceeded");
+}

package/src/sdk/session-reconnect.ts

@@ -1,5 +1,5 @@
 import { HEARTBEAT_TTL_MS } from "./bus/daemon-paths";
-import type { SdkClientOptions } from "./client";
+import { DEFAULT_SDK_REQUEST_TIMEOUT_MS, type SdkClientOptions } from "./client";
 
 type SessionReconnectOptions = Required<
 	Pick<SdkClientOptions, "reconnectAttempts" | "reconnectBackoffMs" | "reconnectMaxBackoffMs">
@@ -41,3 +41,47 @@ export const ACP_SESSION_RECONNECT: SessionReconnectOptions = {
 	reconnectBackoffMs: SESSION_RECONNECT_BACKOFF_MS,
 	reconnectMaxBackoffMs: SESSION_RECONNECT_MAX_BACKOFF_MS,
 };
+
+/**
+ * Post-connect response budget for session-scoped SDK commands dispatched
+ * through the Router. It bounds the wait for a reply on an already-connected
+ * transport; connecting, reconnecting, and lifecycle work keep their own
+ * separate deadlines.
+ *
+ * The transport default (10s) is sized for one-shot broker requests and is too
+ * short for the first query a cold session host answers: Q10
+ * (`models.list/current`) collects credentials for every configured profile
+ * provider, which on a multi-OAuth setup takes longer than 10s once and
+ * milliseconds afterwards. Abandoning that request loses far more than the
+ * query — the reply lands after the deadline, so the outcome can only be
+ * reported as uncertain after the frame was sent, and ACP discards the session
+ * it just created (#4258).
+ *
+ * The size is the SDK's existing model of what one healthy round trip may cost
+ * while the producer is still working: an owner heartbeat window plus a second
+ * window for recovery ({@link ACP_SESSION_RECONNECT}, and `SDK_RECONNECT_BUDGET_MS`
+ * in `./prompt-watchdog`, both `2 * HEARTBEAT_TTL_MS`). A response budget shorter
+ * than the recovery budget would abandon replies the rest of the stack is still
+ * waiting to deliver.
+ *
+ * Session commands are acknowledgement-shaped (`turn.prompt` returns an accepted
+ * receipt, not the turn's result), so no legitimate session request needs longer.
+ * The tradeoff is that a connected but wedged host is reported after this budget
+ * rather than after 10s, including `turn.abort`: ACP awaits that acknowledgement
+ * before arming its own settlement grace (`CANCEL_SETTLEMENT_GRACE_MS`), which
+ * bounds only the terminal that follows an acknowledged abort.
+ */
+export const SESSION_REQUEST_TIMEOUT_MS = 2 * HEARTBEAT_TTL_MS;
+
+/**
+ * Reply budget for `turn.abort`, which cannot use {@link SESSION_REQUEST_TIMEOUT_MS}.
+ *
+ * A cancel is the user asking for the turn to stop now, and the caller waits for
+ * its acknowledgement before anything else can bound the turn: ACP arms its own
+ * settlement grace only after `aborted: true` comes back, so an abort that waits
+ * the full session budget delays cancellation by that budget and, if it finally
+ * rejects, leaves the prompt for the inactivity watchdog instead of the cancel
+ * path. Aborting therefore keeps the ordinary one-shot request deadline: the
+ * abort is not the query whose cold first answer needed a wider budget (#4258).
+ */
+export const SESSION_ABORT_TIMEOUT_MS = DEFAULT_SDK_REQUEST_TIMEOUT_MS;