@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/sdk/host/host.ts

@@ -0,0 +1,296 @@
+import { type EventFrame, SessionEventStream } from "./events";
+import { type ProviderLease, ReverseLeaseError, ReverseLeaseRuntime } from "./reverse-leases";
+import type { BrokerIndexWriter, HostEndpointAdapters, SdkFrame } from "./types";
+
+export type SdkRequestObserver = (kind: "control" | "query", connectionId: string, frame: SdkFrame) => void;
+
+export interface SessionSdkHostOptions extends HostEndpointAdapters {
+	control?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
+	query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
+	/** Best-effort diagnostic observation of accepted control/query frames. */
+	onRequest?: SdkRequestObserver;
+	/** Runs only after a successful control response has been sent to the client. */
+	afterControlResponse?: (connectionId: string, request: SdkFrame, response: SdkFrame) => void | Promise<void>;
+	installProviderDefinitions?: (capability: string, definitions: unknown) => void;
+	onProviderDefinitionsRemoved?: (capability: string) => void;
+	onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
+}
+
+/** 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";
+}
+
+function errorFrame(connectionId: string, frame: SdkFrame, error: unknown): SdkFrame {
+	const candidate = error as { code?: unknown; message?: unknown };
+	const code =
+		error instanceof ReverseLeaseError
+			? error.code
+			: typeof candidate?.code === "string"
+				? candidate.code
+				: "internal";
+	const message = typeof candidate?.message === "string" ? candidate.message : "SDK host operation failed.";
+	return {
+		type: "reverse_response",
+		id: typeof frame.id === "string" ? frame.id : "",
+		connectionId,
+		leaseId: typeof frame.leaseId === "string" ? frame.leaseId : "",
+		ok: false,
+		error: { code, message },
+	};
+}
+
+function leaseState(id: unknown, lease: ProviderLease, active = lease.active): SdkFrame {
+	return {
+		type: "lease_state",
+		id: typeof id === "string" ? id : "",
+		connectionId: lease.connectionId,
+		capability: lease.capability,
+		leaseId: lease.leaseId,
+		leaseExpiresAt: new Date(lease.expiresAt).toISOString(),
+		active,
+	};
+}
+
+function registeredNames(definitions: unknown): string[] {
+	const entries = Array.isArray(definitions)
+		? definitions
+		: definitions && typeof definitions === "object"
+			? Object.values(definitions as Record<string, unknown>).flatMap(value => (Array.isArray(value) ? value : []))
+			: [];
+	return entries.flatMap(entry =>
+		entry && typeof entry === "object" && typeof (entry as Record<string, unknown>).name === "string"
+			? [(entry as Record<string, string>).name]
+			: [],
+	);
+}
+
+function invalidFrame(message: string): Error {
+	return Object.assign(new Error(message), { code: "invalid_reverse_frame" });
+}
+function record(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+function requiredString(frame: SdkFrame, field: string): string {
+	const value = frame[field];
+	if (typeof value !== "string") throw invalidFrame(`${field} must be a string.`);
+	return value;
+}
+function optionalString(frame: SdkFrame, field: string): string | undefined {
+	const value = frame[field];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw invalidFrame(`${field} must be a string.`);
+	return value;
+}
+function requireConnection(connectionId: string, frame: SdkFrame): void {
+	if (requiredString(frame, "connectionId") !== connectionId)
+		throw invalidFrame("connectionId does not match the transport connection.");
+}
+function has(frame: SdkFrame, field: string): boolean {
+	return Object.hasOwn(frame, field);
+}
+
+/** Adapter-based session host; bus wiring owns NotificationServer creation and transport framing. */
+export class SessionSdkHost {
+	readonly events = new SessionEventStream();
+	readonly reverse: ReverseLeaseRuntime;
+	readonly #options: SessionSdkHostOptions;
+	#started = false;
+	#unsubscribe?: () => void;
+	#registration?: { writer: BrokerIndexWriter; generation: number };
+
+	constructor(options: SessionSdkHostOptions) {
+		this.#options = options;
+		this.reverse = new ReverseLeaseRuntime({
+			sendFrame: options.sendFrame,
+			installDefinitions: options.installProviderDefinitions,
+			onDefinitionsRemoved: options.onProviderDefinitionsRemoved,
+			onCancel: options.onReverseCancel,
+		});
+	}
+
+	get started(): boolean {
+		return this.#started;
+	}
+	get generation(): number {
+		return this.events.generation;
+	}
+	/** Current installed definitions for a live provider capability. */
+	getProviderDefinitions(capability: string): unknown | undefined {
+		return this.reverse.getInstalledDefinitions(capability);
+	}
+	/** Release reverse leases after the transport reports a WebSocket disconnect. */
+	handleDisconnect(connectionId: string): void {
+		this.reverse.disconnect(connectionId);
+	}
+
+	/** Adds an event to the resumable event ring. Transport delivery is owned by bus wiring. */
+	emitEvent(frame: SdkFrame): EventFrame {
+		return this.events.emit(frame);
+	}
+
+	async start(): Promise<"started" | "already"> {
+		if (this.#started) return "already";
+		this.events.restart();
+		this.emitEvent({ name: "session_ready", sessionId: this.#options.sessionId, generation: this.events.generation });
+		const disposer = this.#options.onFrame((connectionId, frame) => {
+			void this.#onFrame(connectionId, frame);
+		});
+		this.#unsubscribe = typeof disposer === "function" ? disposer : undefined;
+		this.#started = true;
+		if (this.#registration)
+			await this.#registration.writer.register({
+				sessionId: this.#options.sessionId,
+				stateRoot: this.#options.stateRoot,
+				endpointGeneration: this.events.generation,
+			});
+		return "started";
+	}
+
+	async stop(): Promise<"stopped" | "already"> {
+		if (!this.#started) return "already";
+		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,
+			});
+		return "stopped";
+	}
+
+	async registerWithBroker(writer: BrokerIndexWriter): Promise<void> {
+		this.#registration = { writer, generation: this.events.generation };
+		if (this.#started)
+			await writer.register({
+				sessionId: this.#options.sessionId,
+				stateRoot: this.#options.stateRoot,
+				endpointGeneration: this.events.generation,
+			});
+	}
+
+	async #send(connectionId: string, frame: SdkFrame): Promise<void> {
+		await this.#options.sendFrame(connectionId, frame);
+	}
+
+	async #onFrame(connectionId: string, frame: SdkFrame): Promise<void> {
+		try {
+			switch (frame.type) {
+				case "control_request": {
+					this.#observeRequest("control", connectionId, frame);
+					const result = await this.#options.control?.(connectionId, frame);
+					if (result !== undefined) {
+						const response = { type: "control_response", ...(result as SdkFrame) };
+						await this.#send(connectionId, response);
+						await this.#options.afterControlResponse?.(connectionId, frame, response);
+					}
+					break;
+				}
+				case "event_replay": {
+					const id = requiredString(frame, "id");
+					const rawGeneration =
+						frame.sinceGeneration === undefined ? this.events.generation : frame.sinceGeneration;
+					const rawSeq = frame.sinceSeq === undefined ? 0 : frame.sinceSeq;
+					if (typeof rawGeneration !== "number" || !Number.isSafeInteger(rawGeneration) || rawGeneration < 0)
+						throw invalidFrame("sinceGeneration must be a non-negative integer.");
+					if (typeof rawSeq !== "number" || !Number.isSafeInteger(rawSeq) || rawSeq < 0)
+						throw invalidFrame("sinceSeq must be a non-negative integer.");
+					const sinceGeneration = rawGeneration;
+					const sinceSeq = rawSeq;
+					const replay = this.events.replay(sinceSeq, sinceGeneration);
+					await this.#send(connectionId, {
+						type: "event_replay_result",
+						id,
+						ok: true,
+						...replay,
+						generation: this.events.generation,
+						lastSeq: this.events.sequence,
+					});
+					break;
+				}
+				case "query_request": {
+					this.#observeRequest("query", connectionId, frame);
+					const result = await this.#options.query?.(connectionId, frame);
+					if (result !== undefined)
+						await this.#send(connectionId, { type: "query_response", ...(result as SdkFrame) });
+					break;
+				}
+				case "register_provider": {
+					requiredString(frame, "id");
+					requireConnection(connectionId, frame);
+					const capability = requiredString(frame, "capability");
+					if (!has(frame, "definitions")) throw invalidFrame("definitions is required.");
+					const lease = this.reverse.registerProvider(
+						connectionId,
+						capability,
+						frame.definitions,
+						optionalString(frame, "expectedLeaseId"),
+						optionalString(frame, "idempotencyKey"),
+					);
+					await this.#send(connectionId, {
+						id: frame.id,
+						type: "register_provider_result",
+						leaseId: lease.leaseId,
+						leaseExpiresAt: new Date(lease.expiresAt).toISOString(),
+						registeredNames: registeredNames(frame.definitions),
+					});
+					break;
+				}
+				case "provider_heartbeat": {
+					requireConnection(connectionId, frame);
+					const lease = this.reverse.heartbeat(connectionId, requiredString(frame, "leaseId"));
+					await this.#send(connectionId, leaseState(undefined, lease));
+					break;
+				}
+				case "lease_release": {
+					requireConnection(connectionId, frame);
+					const handoffTo = optionalString(frame, "handoffTo");
+					const lease = this.reverse.release(connectionId, requiredString(frame, "leaseId"), handoffTo);
+					await this.#send(connectionId, leaseState(undefined, lease));
+					break;
+				}
+				case "reverse_response": {
+					const id = requiredString(frame, "id");
+					requireConnection(connectionId, frame);
+					const leaseId = requiredString(frame, "leaseId");
+					if (typeof frame.ok !== "boolean") throw invalidFrame("ok must be a boolean.");
+					const responseError = record(frame.error);
+					if (frame.ok) {
+						if (!has(frame, "result") || has(frame, "error"))
+							throw invalidFrame("Successful reverse responses require result and no error.");
+						this.reverse.respond(connectionId, id, leaseId, frame.result);
+					} else {
+						if (
+							has(frame, "result") ||
+							!responseError ||
+							typeof responseError.code !== "string" ||
+							typeof responseError.message !== "string"
+						)
+							throw invalidFrame("Failed reverse responses require a structured error and no result.");
+						this.reverse.respond(connectionId, id, leaseId, undefined, {
+							code: responseError.code,
+							message: responseError.message,
+						});
+					}
+					break;
+				}
+				default:
+					// Unknown/future frame types are tolerated silently per the v3
+					// forward-compatibility contract; only malformed frames of KNOWN
+					// types produce structured errors (thrown above).
+					return;
+			}
+		} catch (error) {
+			await this.#send(connectionId, errorFrame(connectionId, frame, error));
+		}
+	}
+	#observeRequest(kind: "control" | "query", connectionId: string, frame: SdkFrame): void {
+		try {
+			this.#options.onRequest?.(kind, connectionId, frame);
+		} catch {
+			// Diagnostic observers must not change request handling.
+		}
+	}
+}

package/src/sdk/host/index.ts

@@ -0,0 +1,4 @@
+export * from "./events";
+export * from "./host";
+export * from "./reverse-leases";
+export * from "./types";

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

@@ -0,0 +1,189 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { MAX_PINNED_REVISIONS, type RevisionStore, RevisionStoreError, SNAPSHOT_TTL_MS } from "./revision-store.js";
+
+export const CURSOR_TTL_MS = SNAPSHOT_TTL_MS;
+export const MAX_CURSORS_PER_CONNECTION = 32;
+export const MAX_CURSORS_PER_SESSION = MAX_PINNED_REVISIONS;
+
+export interface CursorEnvelope {
+	cursorVersion: 1;
+	protocolMajor: 3;
+	sessionId: string;
+	resource: string;
+	revision: string;
+	highWatermark?: unknown;
+	position: unknown;
+	direction: string;
+	pageShape: unknown;
+}
+
+export interface CursorSelector {
+	queryId: string;
+	entryId?: string;
+	field?: string;
+	fileId?: string;
+	hunkId?: string;
+	resourceKind?: string;
+	resourceId?: string;
+	itemId?: string;
+}
+
+export interface CursorPosition {
+	offset?: number;
+	byteOffset?: number;
+	selector?: CursorSelector;
+}
+
+export function cursorSelector(position: unknown): CursorSelector | undefined {
+	if (!position || typeof position !== "object") return undefined;
+	const selector = (position as CursorPosition).selector;
+	return selector && typeof selector.queryId === "string" ? selector : undefined;
+}
+
+export function assertCursorSelector(
+	cursor: CursorSelector | undefined,
+	requested: Partial<CursorSelector>,
+): CursorSelector {
+	if (!cursor) throw new CursorError("invalid_input", false, "cursor does not match query");
+	for (const [key, value] of Object.entries(requested)) {
+		if (value !== undefined && cursor[key as keyof CursorSelector] !== value)
+			throw new CursorError("invalid_input", false, "cursor does not match query");
+	}
+	return cursor;
+}
+
+export interface CursorQueryContext {
+	sessionId: string;
+	resource?: string;
+	resourceId?: string;
+	direction: string;
+	pageShape: unknown;
+}
+
+export class CursorError extends Error {
+	constructor(
+		readonly code:
+			| "cursor_expired"
+			| "invalid_cursor"
+			| "invalid_input"
+			| "resource_gone"
+			| "snapshot_capacity_exceeded",
+		readonly restartQuery = code === "cursor_expired",
+		message: string = code,
+	) {
+		super(message);
+	}
+}
+
+function canonicalise(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(canonicalise);
+	if (value && typeof value === "object")
+		return Object.fromEntries(
+			Object.entries(value)
+				.sort(([a], [b]) => a.localeCompare(b))
+				.map(([key, entry]) => [key, canonicalise(entry)]),
+		);
+	return value;
+}
+
+function canonicalJson(value: unknown): string {
+	return JSON.stringify(canonicalise(value));
+}
+export function canonicalCursorJson(envelope: CursorEnvelope): string {
+	return canonicalJson(envelope);
+}
+export function cursorMac(envelope: CursorEnvelope, sessionToken: string | Uint8Array): string {
+	return createHmac("sha256", sessionToken).update(canonicalCursorJson(envelope)).digest("hex");
+}
+export function signCursor(envelope: CursorEnvelope, sessionToken: string | Uint8Array): string {
+	return JSON.stringify({ envelope, mac: cursorMac(envelope, sessionToken) });
+}
+export function verifyCursor(cursor: string, sessionToken: string | Uint8Array): CursorEnvelope | undefined {
+	try {
+		const signed = JSON.parse(cursor) as { envelope: CursorEnvelope; mac: string };
+		const expected = Buffer.from(cursorMac(signed.envelope, sessionToken), "hex");
+		const actual = Buffer.from(signed.mac, "hex");
+		if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return undefined;
+		const envelope = signed.envelope;
+		return envelope.cursorVersion === 1 && envelope.protocolMajor === 3 ? envelope : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+interface ActiveCursor {
+	connectionId: string;
+	resourceId: string;
+	expiresAt: number;
+}
+
+/** Tracks cursor budgets and binds snapshot pins to authenticated cursor strings. */
+export class CursorRegistry {
+	readonly #active = new Map<string, ActiveCursor>();
+	constructor(
+		private readonly sessionToken: string | Uint8Array,
+		private readonly revisions: RevisionStore,
+		private readonly now: () => number = Date.now,
+	) {}
+
+	async grant(
+		connectionId: string,
+		envelope: CursorEnvelope,
+		resourceKind: string,
+		resourceId: string,
+	): Promise<string> {
+		this.sweep();
+		if (
+			this.#active.size >= MAX_CURSORS_PER_SESSION ||
+			[...this.#active.values()].filter(item => item.connectionId === connectionId).length >=
+				MAX_CURSORS_PER_CONNECTION
+		)
+			throw new CursorError("snapshot_capacity_exceeded", false);
+		const cursor = signCursor(envelope, this.sessionToken);
+		try {
+			await this.revisions.pin(cursor, resourceKind, resourceId, envelope.revision);
+		} catch (error) {
+			if (error instanceof RevisionStoreError) throw new CursorError(error.code, false);
+			throw error;
+		}
+		this.#active.set(cursor, { connectionId, resourceId, expiresAt: this.now() + CURSOR_TTL_MS });
+		return cursor;
+	}
+
+	consume(cursor: string, connectionId: string, expected: CursorQueryContext): CursorEnvelope {
+		const envelope = verifyCursor(cursor, this.sessionToken);
+		if (!envelope) throw new CursorError("invalid_cursor", false);
+		const active = this.#active.get(cursor);
+		if (!active || active.connectionId !== connectionId || active.expiresAt <= this.now()) {
+			this.release(cursor);
+			throw new CursorError("cursor_expired");
+		}
+		if (
+			envelope.sessionId !== expected.sessionId ||
+			(expected.resource !== undefined && envelope.resource !== expected.resource) ||
+			envelope.direction !== expected.direction ||
+			canonicalJson(envelope.pageShape) !== canonicalJson(expected.pageShape) ||
+			(expected.resourceId !== undefined && active.resourceId !== expected.resourceId)
+		) {
+			throw new CursorError("invalid_input", false, "cursor does not match query");
+		}
+		this.release(cursor);
+		return envelope;
+	}
+
+	release(cursor: string): void {
+		this.#active.delete(cursor);
+		this.revisions.unpin(cursor);
+	}
+
+	close(): void {
+		for (const cursor of this.#active.keys()) this.release(cursor);
+	}
+	sweep(): void {
+		for (const [cursor, active] of this.#active) if (active.expiresAt <= this.now()) this.release(cursor);
+		this.revisions.sweep();
+	}
+	get size(): number {
+		return this.#active.size;
+	}
+}