@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/sdk/host/reverse-leases.ts

@@ -0,0 +1,325 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { SdkFrame } from "./types";
+
+export const REVERSE_HEARTBEAT_MS = 5_000;
+export const REVERSE_LEASE_TTL_MS = 15_000;
+export const REVERSE_RECLAIM_GRACE_MS = 15_000;
+export const MAX_REVERSE_OUTSTANDING = 64;
+export const MAX_REVERSE_PAYLOAD_BYTES = 256 * 1024;
+
+export class ReverseLeaseError extends Error {
+	constructor(
+		readonly code:
+			| "lease_unavailable"
+			| "lease_expired"
+			| "provider_lease_conflict"
+			| "provider_required"
+			| "not_lease_owner"
+			| "payload_too_large"
+			| "too_many_outstanding"
+			| "unknown_request"
+			| "idempotency_conflict",
+		message = code,
+	) {
+		super(message);
+	}
+}
+
+export interface ProviderLease {
+	leaseId: string;
+	connectionId: string;
+	capability: string;
+	definitions: unknown;
+	expiresAt: number;
+	graceUntil?: number;
+	active: boolean;
+}
+
+interface Outstanding {
+	connectionId: string;
+	capability: string;
+	leaseId: string;
+	resolve: (value: unknown) => void;
+	reject: (reason: Error) => void;
+}
+
+export interface ReverseLeaseOptions {
+	now?: () => number;
+	leaseTtlMs?: number;
+	sendFrame: (connectionId: string, frame: SdkFrame) => void | Promise<void>;
+	installDefinitions?: (capability: string, definitions: unknown) => void;
+	onCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
+	onDefinitionsRemoved?: (capability: string) => void;
+}
+
+function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([left], [right]) => left.localeCompare(right));
+		return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+function registrationFingerprint(capability: string, definitions: unknown, expectedLeaseId?: string): string {
+	return createHash("sha256")
+		.update(canonicalJson({ capability, definitions, expectedLeaseId: expectedLeaseId ?? null }))
+		.digest("hex");
+}
+
+/** Session-local directed reverse RPC lease registry. */
+export class ReverseLeaseRuntime {
+	readonly #now: () => number;
+	readonly #leaseTtlMs: number;
+	readonly #sendFrame: ReverseLeaseOptions["sendFrame"];
+	readonly #installDefinitions?: ReverseLeaseOptions["installDefinitions"];
+	readonly #onDefinitionsRemoved?: ReverseLeaseOptions["onDefinitionsRemoved"];
+	readonly #onCancel?: ReverseLeaseOptions["onCancel"];
+	readonly #leases = new Map<string, ProviderLease>();
+	readonly #idempotency = new Map<string, { fingerprint: string; lease: ProviderLease }>();
+	readonly #outstanding = new Map<string, Outstanding>();
+	readonly #installedCapabilities = new Set<string>();
+	readonly #sweepTimer: ReturnType<typeof setInterval>;
+	#disposing = false;
+
+	constructor(options: ReverseLeaseOptions) {
+		this.#now = options.now ?? Date.now;
+		this.#leaseTtlMs = options.leaseTtlMs ?? REVERSE_LEASE_TTL_MS;
+		this.#sendFrame = options.sendFrame;
+		this.#installDefinitions = options.installDefinitions;
+		this.#onDefinitionsRemoved = options.onDefinitionsRemoved;
+		this.#onCancel = options.onCancel;
+		this.#sweepTimer = setInterval(() => this.#expireStaleLeases(), Math.max(1, this.#leaseTtlMs / 3));
+		this.#sweepTimer.unref?.();
+	}
+
+	registerProvider(
+		connectionId: string,
+		capability: string,
+		definitions: unknown,
+		expectedLeaseId?: string,
+		idempotencyKey?: string,
+	): ProviderLease {
+		if (this.#disposing) throw new Error("reverse runtime is disposing");
+		const key = `${connectionId}\u0000${idempotencyKey ?? ""}`;
+		const fingerprint = registrationFingerprint(capability, definitions, expectedLeaseId);
+		const replay = idempotencyKey ? this.#idempotency.get(key) : undefined;
+		if (replay) {
+			if (replay.fingerprint !== fingerprint) throw new ReverseLeaseError("idempotency_conflict");
+			const current = this.#leases.get(capability);
+			if (replay.lease === current && current?.active && current.expiresAt > this.#now()) return { ...replay.lease };
+		}
+		const now = this.#now();
+		const existing = this.#leases.get(capability);
+		if (existing && existing.expiresAt <= now) this.#removeDefinitions(existing.capability);
+		const pendingHandoff = existing?.active === false && existing.expiresAt > now;
+		if (pendingHandoff) {
+			if (existing!.connectionId !== connectionId || existing!.leaseId !== expectedLeaseId)
+				throw new ReverseLeaseError("provider_lease_conflict");
+			this.#installDefinitionsFor(capability, definitions);
+			const lease: ProviderLease = {
+				leaseId: existing!.leaseId,
+				connectionId,
+				capability,
+				definitions,
+				expiresAt: now + this.#leaseTtlMs,
+				active: true,
+			};
+			this.#leases.set(capability, lease);
+			if (idempotencyKey) this.#idempotency.set(key, { fingerprint, lease });
+			return { ...lease };
+		}
+		const reclaiming =
+			existing?.leaseId === expectedLeaseId && existing?.graceUntil !== undefined && now <= existing.graceUntil;
+		const refreshing =
+			existing?.active !== false && existing?.connectionId === connectionId && existing.expiresAt > now;
+		if (existing && !reclaiming && !refreshing && existing.connectionId !== connectionId && existing.expiresAt > now)
+			throw new ReverseLeaseError("provider_lease_conflict");
+		this.#installDefinitionsFor(capability, definitions);
+		const lease: ProviderLease = {
+			leaseId: reclaiming || refreshing ? existing!.leaseId : randomUUID(),
+			connectionId,
+			capability,
+			definitions,
+			expiresAt: now + this.#leaseTtlMs,
+			active: true,
+		};
+		this.#leases.set(capability, lease);
+		if (idempotencyKey) this.#idempotency.set(key, { fingerprint, lease });
+		return { ...lease };
+	}
+
+	heartbeat(connectionId: string, leaseId: string): ProviderLease {
+		const lease = this.#owner(connectionId, leaseId);
+		if (lease.expiresAt <= this.#now()) {
+			this.#removeDefinitions(lease.capability);
+			throw new ReverseLeaseError("lease_expired");
+		}
+		lease.expiresAt = this.#now() + this.#leaseTtlMs;
+		lease.graceUntil = undefined;
+		return { ...lease };
+	}
+
+	release(connectionId: string, leaseId: string, handoffTo?: string): ProviderLease {
+		const lease = this.#owner(connectionId, leaseId);
+		this.#cancelForConnection(connectionId, "lease_released");
+		this.#removeDefinitions(lease.capability);
+		if (handoffTo) {
+			lease.connectionId = handoffTo;
+			lease.expiresAt = this.#now() + REVERSE_RECLAIM_GRACE_MS;
+			lease.graceUntil = undefined;
+			lease.active = false;
+			return { ...lease };
+		}
+		this.#leases.delete(lease.capability);
+		return { ...lease };
+	}
+
+	disconnect(connectionId: string): void {
+		const now = this.#now();
+		for (const lease of this.#leases.values())
+			if (lease.connectionId === connectionId) {
+				lease.expiresAt = now;
+				lease.graceUntil = now + REVERSE_RECLAIM_GRACE_MS;
+				this.#removeDefinitions(lease.capability);
+			}
+		this.#cancelForConnection(connectionId, "provider_disconnected");
+	}
+
+	request(capability: string, method: string, payload: unknown): Promise<unknown> {
+		if (this.#disposing) throw new Error("reverse runtime is disposing");
+		this.#assertPayload(payload);
+		const lease = this.#liveLease(capability);
+		if (!lease) {
+			const reservation = this.#leases.get(capability);
+			if (reservation?.active === false && reservation.expiresAt > this.#now())
+				throw new ReverseLeaseError("lease_unavailable");
+			throw new ReverseLeaseError("provider_required");
+		}
+		if (this.#outstanding.size >= MAX_REVERSE_OUTSTANDING) throw new ReverseLeaseError("too_many_outstanding");
+		const id = randomUUID();
+		return new Promise((resolve, reject) => {
+			this.#outstanding.set(id, {
+				connectionId: lease.connectionId,
+				capability,
+				leaseId: lease.leaseId,
+				resolve,
+				reject,
+			});
+			let delivery: void | Promise<void>;
+			try {
+				delivery = this.#sendFrame(lease.connectionId, {
+					type: "reverse_request",
+					id,
+					capability,
+					connectionId: lease.connectionId,
+					leaseId: lease.leaseId,
+					payload: { method, payload },
+				});
+			} catch (error) {
+				this.#outstanding.delete(id);
+				reject(error instanceof Error ? error : new Error(String(error)));
+				return;
+			}
+			Promise.resolve(delivery).catch(error => {
+				this.#outstanding.delete(id);
+				reject(error instanceof Error ? error : new Error(String(error)));
+			});
+		});
+	}
+
+	respond(
+		connectionId: string,
+		id: string,
+		leaseId: string,
+		result: unknown,
+		error?: { code: string; message: string },
+	): void {
+		this.#assertPayload(result);
+		const request = this.#outstanding.get(id);
+		if (!request) throw new ReverseLeaseError("unknown_request");
+		if (request.connectionId !== connectionId || request.leaseId !== leaseId)
+			throw new ReverseLeaseError("not_lease_owner");
+		this.#outstanding.delete(id);
+		if (error) {
+			const rejection = new Error(error.message);
+			rejection.name = error.code;
+			request.reject(rejection);
+		} else request.resolve(result);
+	}
+
+	getLease(capability: string): ProviderLease | undefined {
+		const lease = this.#liveLease(capability);
+		return lease && { ...lease };
+	}
+
+	/** Installed definitions are observable only while their provider lease is live. */
+	getInstalledDefinitions(capability: string): unknown | undefined {
+		return this.#liveLease(capability)?.definitions;
+	}
+
+	dispose(): void {
+		if (this.#disposing) return;
+		this.#disposing = true;
+		clearInterval(this.#sweepTimer);
+		const outstanding = [...this.#outstanding.entries()];
+		const installedCapabilities = [...this.#installedCapabilities];
+		this.#outstanding.clear();
+		this.#installedCapabilities.clear();
+		this.#leases.clear();
+		this.#idempotency.clear();
+		for (const [id, request] of outstanding) {
+			request.reject(new Error("request_cancelled"));
+			try {
+				this.#onCancel?.(id, "lease_released");
+			} catch {}
+		}
+		for (const capability of installedCapabilities) {
+			try {
+				this.#onDefinitionsRemoved?.(capability);
+			} catch {}
+		}
+		this.#disposing = false;
+	}
+
+	#owner(connectionId: string, leaseId: string): ProviderLease {
+		const lease = [...this.#leases.values()].find(candidate => candidate.leaseId === leaseId);
+		if (!lease?.active || lease.connectionId !== connectionId) throw new ReverseLeaseError("not_lease_owner");
+		return lease;
+	}
+	#liveLease(capability: string): ProviderLease | undefined {
+		const lease = this.#leases.get(capability);
+		if (!lease?.active || lease.expiresAt <= this.#now()) {
+			if (lease?.expiresAt !== undefined && lease.expiresAt <= this.#now()) this.#removeDefinitions(capability);
+			return undefined;
+		}
+		return lease;
+	}
+	#expireStaleLeases(): void {
+		for (const lease of this.#leases.values())
+			if (lease.expiresAt <= this.#now()) this.#removeDefinitions(lease.capability);
+	}
+	#cancelForConnection(connectionId: string, reason: "provider_disconnected" | "lease_released"): void {
+		for (const [id, request] of this.#outstanding)
+			if (request.connectionId === connectionId) {
+				this.#outstanding.delete(id);
+				request.reject(new Error("request_cancelled"));
+				this.#onCancel?.(id, reason);
+			}
+	}
+	#installDefinitionsFor(capability: string, definitions: unknown): void {
+		this.#installDefinitions?.(capability, definitions);
+		this.#installedCapabilities.add(capability);
+	}
+	#removeDefinitions(capability: string): void {
+		if (!this.#installedCapabilities.delete(capability)) return;
+		this.#onDefinitionsRemoved?.(capability);
+	}
+	#assertPayload(payload: unknown): void {
+		const encoded = JSON.stringify(payload);
+		if (encoded !== undefined && Buffer.byteLength(encoded) > MAX_REVERSE_PAYLOAD_BYTES)
+			throw new ReverseLeaseError("payload_too_large");
+	}
+}

package/src/sdk/host/types.ts

@@ -0,0 +1,29 @@
+export type SdkFrame = Record<string, unknown>;
+
+/** Narrow common surface shared by control and query adapters. */
+export interface SessionSurface {
+	sessionId: string;
+}
+
+export interface SessionOperationSurface extends SessionSurface {
+	/** Query rows backed by this session's installed binding map. */
+	installedQueries?: ReadonlySet<string>;
+}
+
+/** Operations the neutral control dispatcher may require from a session. */
+export interface ControlSurface extends SessionSurface {
+	[key: string]: unknown;
+}
+
+export interface HostEndpointAdapters {
+	sessionId: string;
+	stateRoot: string;
+	token: string;
+	sendFrame: (connectionId: string, frame: SdkFrame) => void | Promise<void>;
+	onFrame: (handler: (connectionId: string, frame: SdkFrame) => void) => undefined | (() => void);
+}
+
+export interface BrokerIndexWriter {
+	register(input: { sessionId: string; stateRoot: string; endpointGeneration: number }): void | Promise<void>;
+	unregister?(input: { sessionId: string; stateRoot: string; endpointGeneration: number }): void | Promise<void>;
+}

package/src/sdk/index.ts

@@ -0,0 +1,13 @@
+export * as bus from "./bus";
+export * from "./client";
+export * as host from "./host";
+export * as mcp from "./mcp";
+export type {
+	Q10CurrentThinkingLevel,
+	Q10Model,
+	Q10SettableThinkingLevel,
+	Q10ThinkingCapabilities,
+	Q10ThinkingEffort,
+	Q10ThinkingMode,
+} from "./models";
+export * from "./session";

package/src/sdk/lifecycle-session.ts

@@ -0,0 +1,39 @@
+import type { AgentSession } from "../session/agent-session";
+import { type CreateAgentSessionOptions, createAgentSession } from "./session";
+import {
+	lifecycleStartupCapabilityOption,
+	SdkStartupCapability,
+	type SdkStartupFailure,
+	SdkStartupRollbackTracker,
+} from "./startup-capability";
+
+export type CreateLifecycleAgentSessionResult =
+	| {
+			session: AgentSession;
+			capability: SdkStartupCapability;
+			rollback: SdkStartupRollbackTracker;
+	  }
+	| { capability: SdkStartupCapability; rollback: SdkStartupRollbackTracker; failure: SdkStartupFailure };
+
+/** Internal lifecycle-only session construction with an owner-bound SDK startup result. */
+export async function createLifecycleAgentSession(
+	options: CreateAgentSessionOptions = {},
+): Promise<CreateLifecycleAgentSessionResult> {
+	const rollback = new SdkStartupRollbackTracker();
+	const capability = new SdkStartupCapability(rollback);
+	try {
+		const internalOptions = {
+			...options,
+			[lifecycleStartupCapabilityOption]: capability,
+		} as CreateAgentSessionOptions & { [lifecycleStartupCapabilityOption]: SdkStartupCapability };
+		const result = await createAgentSession(internalOptions);
+		if (!result.session.extensionRunner)
+			capability.settleFailure(capability.normalizeFailure("registration", "runner_absent"));
+		return { session: result.session, capability, rollback };
+	} catch (error) {
+		const settled = capability.settleFailure(capability.normalizeFailure("registration", "failed", error));
+		const failure =
+			settled.status === "failed" ? settled.failure : capability.normalizeFailure("registration", "failed", error);
+		return { capability, rollback, failure };
+	}
+}

package/src/sdk/mcp/index.ts

@@ -0,0 +1 @@
+export * from "./server";