@gajae-code/coding-agent 0.12.5 → 0.12.7

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

@@ -94,6 +94,18 @@ export interface TopicDeleteAuthoritySnapshot {
 	record?: TopicRecord;
 }
 
+/**
+ * Proof that a definite delete was settled in memory and still owes its durable
+ * commit. Handed back only by a settlement that actually happened, so a refused
+ * settlement structurally cannot be followed by a rollback.
+ */
+export interface TopicSettledDelete {
+	sessionId: string;
+	topicId: string;
+	/** Authority epoch proven current when the record was removed. */
+	settledEpoch: number;
+}
+
 function isValidBindingString(value: unknown): value is string {
 	return typeof value === "string" && value.trim().length > 0;
 }
@@ -136,6 +148,16 @@ function isValidTopicId(value: unknown): value is string {
 	);
 }
 
+/**
+ * Monotonic epoch successor that saturates instead of leaving the safe-integer
+ * range. Past `Number.MAX_SAFE_INTEGER` two distinct generations collapse onto
+ * the same IEEE-754 double, which would let a stale settlement clear a newer
+ * fence; settlement refuses the saturated value instead of overflowing past it.
+ */
+function nextAuthorityEpoch(current: number): number {
+	return current >= Number.MAX_SAFE_INTEGER ? Number.MAX_SAFE_INTEGER : current + 1;
+}
+
 export function emptyTopicRegistryState(): TopicRegistryState {
 	return { topics: {} };
 }
@@ -161,6 +183,8 @@ export class TopicRegistry {
 	private readonly creatingBindings = new Map<string, TopicEndpointBinding>();
 	/** Monotonic authority epochs, including deletion fences for absent records. */
 	private readonly epochs = new Map<string, number>();
+	/** Phase-1 settlements awaiting their durable clear; their topic ids stay quarantined. */
+	readonly #settling = new Map<string, { topicId: string; settledEpoch: number; record: TopicRecord }>();
 
 	constructor(state: TopicRegistryState = emptyTopicRegistryState()) {
 		this.topics = new Map();
@@ -173,6 +197,7 @@ export class TopicRegistry {
 		this.byTopic.clear();
 		this.#ambiguousTopicIds.clear();
 		this.epochs.clear();
+		this.#settling.clear();
 		this.load(state);
 	}
 
@@ -259,6 +284,10 @@ export class TopicRegistry {
 	private rebuildInboundRoutes(): void {
 		this.byTopic.clear();
 		this.#ambiguousTopicIds.clear();
+		// A settled-but-not-yet-durable clear keeps its topic id quarantined: the
+		// clear is not authoritative until persisted, so no colliding survivor may
+		// become routable and no settled id may become adoptable during that write.
+		for (const settling of this.#settling.values()) this.#ambiguousTopicIds.add(settling.topicId);
 		const activeByTopic = new Map<string, string>();
 
 		for (const [sessionId, record] of this.topics) {
@@ -278,6 +307,13 @@ export class TopicRegistry {
 		}
 	}
 
+	/** Advance and publish the session authority epoch, saturating at the safe-integer bound. */
+	#advanceAuthorityEpoch(sessionId: string, base: number): number {
+		const epoch = nextAuthorityEpoch(base);
+		this.epochs.set(sessionId, epoch);
+		return epoch;
+	}
+
 	/** Resolve the owning session for a topic id (for fail-closed inbound routing). */
 	sessionForTopic(topicId: string): string | undefined {
 		return this.byTopic.get(topicId);
@@ -482,6 +518,7 @@ export class TopicRegistry {
 		const pending = this.inflight.get(sessionId);
 		if (pending) return pending;
 		const epoch = this.epochs.get(sessionId) ?? 0;
+		if (epoch >= Number.MAX_SAFE_INTEGER) throw new Error("topic authority epoch exhausted");
 		// Publish the compatible endpoint claim before invoking `create`: the callback
 		// may immediately begin a remote create and identity-less recovery must never
 		// observe a false absence during that await.
@@ -676,7 +713,9 @@ export class TopicRegistry {
 	/** Restore a failed delete fence only while its exact authority mutation remains current. */
 	restoreDeleteAuthority(snapshot: TopicDeleteAuthoritySnapshot): boolean {
 		const record = this.topics.get(snapshot.sessionId);
-		const deleteEpoch = Math.max(snapshot.fenceEpoch ?? 0, snapshot.authorityEpoch ?? 0) + 1;
+		const authorityBase = Math.max(snapshot.fenceEpoch ?? 0, snapshot.authorityEpoch ?? 0);
+		if (authorityBase >= Number.MAX_SAFE_INTEGER) return false;
+		const deleteEpoch = nextAuthorityEpoch(authorityBase);
 		if (this.epochs.get(snapshot.sessionId) !== deleteEpoch) return false;
 		if (snapshot.topicId === undefined) {
 			if (record) return false;
@@ -697,10 +736,17 @@ export class TopicRegistry {
 		return true;
 	}
 
-	/** Restore the exact delete fence after a failed compensation publication. */
+	/**
+	 * Restore the exact delete fence after a failed compensation publication.
+	 *
+	 * Settlement rebuilds derived routes, which can make a surviving colliding
+	 * record routable. Rebuild again on successful restoration so the reinstated
+	 * fence re-quarantines the topic id instead of leaving inbound routing open to
+	 * the collision partner despite the restored fence.
+	 */
 	restoreDeleteFence(snapshot: TopicDeleteAuthoritySnapshot): boolean {
 		const record = this.topics.get(snapshot.sessionId);
-		const deleteEpoch = Math.max(snapshot.fenceEpoch ?? 0, snapshot.authorityEpoch ?? 0) + 1;
+		const deleteEpoch = nextAuthorityEpoch(Math.max(snapshot.fenceEpoch ?? 0, snapshot.authorityEpoch ?? 0));
 		if (snapshot.topicId === undefined) {
 			if (record) return false;
 		} else if (!record) {
@@ -715,17 +761,19 @@ export class TopicRegistry {
 		} else {
 			record.authorityEpoch = deleteEpoch;
 			record.authorityState = "delete_pending";
-			if (this.byTopic.get(record.topicId) === snapshot.sessionId) this.byTopic.delete(record.topicId);
 		}
 		this.epochs.set(snapshot.sessionId, deleteEpoch);
+		this.rebuildInboundRoutes();
 		return true;
 	}
 
 	/** 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);
-		const epoch = Math.max(this.epochs.get(sessionId) ?? 0, record?.authorityEpoch ?? 0) + 1;
-		this.epochs.set(sessionId, epoch);
+		const epoch = this.#advanceAuthorityEpoch(
+			sessionId,
+			Math.max(this.epochs.get(sessionId) ?? 0, record?.authorityEpoch ?? 0),
+		);
 		if (!record) return undefined;
 		record.authorityEpoch = epoch;
 		record.authorityState = "delete_pending";
@@ -799,11 +847,86 @@ export class TopicRegistry {
 		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 {
+	/**
+	 * Phase 1 of settling a definite remote delete: remove the record while
+	 * deliberately RETAINING its topic-id quarantine.
+	 *
+	 * `dispatchedAuthorityEpoch` is the authority epoch the caller held when it
+	 * dispatched the remote delete. Settlement requires that epoch to still equal
+	 * both the record's own authority epoch and the registry's current epoch for
+	 * the session, so a held earlier delete can never settle a newer fence: if a
+	 * scan or close-started delete re-fenced the same session/topic after this
+	 * delete was dispatched, the stale definite result is refused and the newer
+	 * `delete_pending` record plus its topic-id quarantine stay intact.
+	 *
+	 * An epoch outside the safe-integer range cannot identify a generation, and at
+	 * `Number.MAX_SAFE_INTEGER` epoch advancement has saturated so distinct
+	 * generations are no longer distinguishable. Both fail closed: settlement can
+	 * no longer be proven fresh, so the fence is kept.
+	 *
+	 * Derived routing tables are deliberately NOT rebuilt here. Until the cleared
+	 * snapshot is durably persisted the clear is not authoritative, so publishing
+	 * routes now would make a colliding survivor routable (and the settled id
+	 * adoptable) during the held write, and a failed persist would re-quarantine
+	 * too late. Publish with {@link commitSettledDelete} once the persist
+	 * succeeds, or undo with {@link rollbackSettledDelete} when it fails.
+	 */
+	settleDelete(sessionId: string, topicId: string, dispatchedAuthorityEpoch: number): TopicSettledDelete | undefined {
+		if (!Number.isSafeInteger(dispatchedAuthorityEpoch) || dispatchedAuthorityEpoch < 0) return undefined;
+		if (this.#settling.has(sessionId)) return undefined;
 		const record = this.topics.get(sessionId);
-		if (!record || record.topicId !== topicId || record.authorityState !== "delete_pending") return false;
+		if (!record || record.topicId !== topicId || record.authorityState !== "delete_pending") return undefined;
+		if ((record.authorityEpoch ?? 0) !== dispatchedAuthorityEpoch) return undefined;
+		const currentEpoch = this.authorityEpoch(sessionId);
+		if (currentEpoch !== dispatchedAuthorityEpoch) return undefined;
+		if (currentEpoch >= Number.MAX_SAFE_INTEGER) return undefined;
 		this.topics.delete(sessionId);
+		this.#settling.set(sessionId, { topicId, settledEpoch: dispatchedAuthorityEpoch, record: { ...record } });
+		this.#ambiguousTopicIds.add(topicId);
+		if (this.byTopic.get(topicId) === sessionId) this.byTopic.delete(topicId);
+		return { sessionId, topicId, settledEpoch: dispatchedAuthorityEpoch };
+	}
+
+	/**
+	 * Phase 2: publish derived routing tables once the cleared state is durable.
+	 *
+	 * Only here does the settled topic id lose its quarantine, so a surviving
+	 * colliding record becomes routable and a settled id becomes adoptable without
+	 * waiting for a daemon restart.
+	 */
+	commitSettledDelete(settled: TopicSettledDelete): boolean {
+		const pending = this.#settling.get(settled.sessionId);
+		if (!pending || pending.topicId !== settled.topicId || pending.settledEpoch !== settled.settledEpoch)
+			return false;
+		this.#settling.delete(settled.sessionId);
+		this.rebuildInboundRoutes();
+		return true;
+	}
+
+	/**
+	 * Compare-and-swap undo for a settlement whose durable clear failed.
+	 *
+	 * Restoration applies only while the registry still holds exactly the state
+	 * that this settlement produced: the settlement is still awaiting commit, the
+	 * session still has no record, and the session epoch is still the settled
+	 * epoch. Any mismatch means a newer generation intervened, so the restore is
+	 * refused and the newer state is left untouched. A refused settlement produced
+	 * no token, so it can never reach this path.
+	 */
+	rollbackSettledDelete(settled: TopicSettledDelete): boolean {
+		const pending = this.#settling.get(settled.sessionId);
+		if (!pending || pending.topicId !== settled.topicId || pending.settledEpoch !== settled.settledEpoch)
+			return false;
+		if (this.topics.has(settled.sessionId)) return false;
+		if (this.authorityEpoch(settled.sessionId) !== settled.settledEpoch) return false;
+		this.#settling.delete(settled.sessionId);
+		this.topics.set(settled.sessionId, {
+			...pending.record,
+			authorityEpoch: settled.settledEpoch,
+			authorityState: "delete_pending",
+		});
+		this.epochs.set(settled.sessionId, settled.settledEpoch);
+		this.rebuildInboundRoutes();
 		return true;
 	}
 
@@ -811,7 +934,7 @@ export class TopicRegistry {
 	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);
+		this.#advanceAuthorityEpoch(sessionId, Math.max(this.epochs.get(sessionId) ?? 0, record.authorityEpoch ?? 0));
 		if (this.byTopic.get(record.topicId) === sessionId) this.byTopic.delete(record.topicId);
 		return this.topics.delete(sessionId);
 	}

package/src/sdk/session.ts

@@ -11,6 +11,7 @@ import {
 } from "@gajae-code/agent-core";
 import {
 	type AssistantMessage,
+	type AttemptScopeRef,
 	type AuthCredentialSelector,
 	type CredentialDisabledEvent,
 	type Message,
@@ -2538,21 +2539,21 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (!obfuscator?.hasSecrets()) return converted;
 			return obfuscateMessages(obfuscator, converted);
 		};
-		const transformContext = async (messages: AgentMessage[], _signal?: AbortSignal) => {
+		const transformContext = async (messages: AgentMessage[], _signal?: AbortSignal, scope?: AttemptScopeRef) => {
 			// External Agent events dispatch listeners without awaiting them. The
 			// session-owned barrier makes any pre-admission artifact transformation
 			// visible before this provider context is normalized.
 			await session?.awaitPendingContextTransformations();
-			return extensionRunner ? await extensionRunner.emitContext(messages) : messages;
+			return extensionRunner ? await extensionRunner.emitContext(messages, scope) : messages;
 		};
 		const onPayload = extensionRunner
-			? async (payload: unknown, _model?: Model) => {
-					return await extensionRunner.emitBeforeProviderRequest(payload);
+			? async (payload: unknown, _model?: Model, scope?: AttemptScopeRef) => {
+					return await extensionRunner.emitBeforeProviderRequest(payload, scope);
 				}
 			: undefined;
 		const onResponse: SimpleStreamOptions["onResponse"] | undefined = extensionRunner
-			? async (response, model) => {
-					await extensionRunner.emitAfterProviderResponse(response, model);
+			? async (response, model, scope) => {
+					await extensionRunner.emitAfterProviderResponse(response, model, scope);
 				}
 			: undefined;