@gajae-code/agent-core 0.12.5 → 0.12.7

package/src/agent.ts

@@ -23,6 +23,8 @@ import {
 import { extractHttpStatusFromError } from "@gajae-code/utils";
 import { agentLoop, agentLoopContinue } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
+import type { AttemptRunHandle, AttemptScope } from "./attempt-scope";
+import { createAttemptScopeAuthority } from "./attempt-scope";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import { assertImagePlaceholdersHavePayload } from "./image-placeholder-guard";
 import { createRunResourceLedger } from "./run-resource-ledger";
@@ -39,11 +41,14 @@ import type {
 	ManagedAttemptDecision,
 	ManagedAttemptOutcome,
 	ManagedLogicalRunId,
+	RunCancellationDomain,
+	RunCancellationDomainBridge,
 	RunResourceLedger,
 	RunTerminalRequest,
 	StreamFn,
 	ToolCallContext,
 } from "./types";
+import { setAgentTerminalOwnerContext } from "./types";
 
 function assertUserImagePlaceholdersHavePayload(messages: readonly AgentMessage[]): void {
 	for (const message of messages) {
@@ -125,7 +130,7 @@ export interface AgentOptions {
 	 * Optional transform applied to context before convertToLlm.
 	 * Use for context pruning, injecting external context, etc.
 	 */
-	transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+	transformContext?: (messages: AgentMessage[], signal?: AbortSignal, scope?: AttemptScope) => Promise<AgentMessage[]>;
 
 	/**
 	 * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
@@ -296,8 +301,11 @@ export interface AgentPromptOptions {
 	toolChoice?: ToolChoice;
 	/** Disable transport replay; fallback accounting is owned by the caller. */
 	fallbackManaged?: boolean;
+	/** Continue a cooperative maintenance checkpoint under its existing logical run and cancellation domain. */
+	maintenanceContinuation?: boolean;
 	/** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
-	onRunAccepted?: () => void;
+	/** Receives the immutable run handle as the first callback argument. */
+	onRunAccepted?: (...args: any[]) => void;
 	/** Called once immediately before every managed upstream request. */
 	nextFallbackAttempt?: AgentLoopConfig["nextFallbackAttempt"];
 	/** Called after a managed upstream request is accepted and committed. */
@@ -330,6 +338,8 @@ export class Agent {
 		error: undefined,
 	};
 	#contextRevision = 0;
+	#attemptAuthority = createAttemptScopeAuthority();
+	#runHandles = new Map<number | ManagedLogicalRunId, AttemptRunHandle>();
 
 	#listeners = new Set<(e: AgentEvent) => void>();
 	#abortController?: AbortController;
@@ -367,8 +377,8 @@ export class Agent {
 	#runSequence = 0;
 	#activeRunId?: number;
 	#activeResourceRunId?: string;
+	#activeResourceCancellationDomain?: RunCancellationDomain;
 	#continuationGeneration = 0;
-	#activeFallbackManaged = false;
 	#kimiApiFormat?: "openai" | "anthropic";
 	#preferWebsockets?: boolean;
 	#transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
@@ -395,6 +405,20 @@ export class Agent {
 	#terminalizedLogicalRunIds = new Set<ManagedLogicalRunId>();
 	#managedLogicalRunOwner?: ManagedLogicalRunId;
 	readonly resourceLedger: RunResourceLedger = createRunResourceLedger();
+	bindRunCancellationDomainBridge(bridge: RunCancellationDomainBridge, agentSessionClaimKey?: object): void {
+		this.resourceLedger.bindCancellationDomainBridge(bridge);
+		if (agentSessionClaimKey) this.resourceLedger.bindAgentSessionClaimKey(agentSessionClaimKey);
+	}
+
+	/** Mint a side-attempt scope and its authority unregister function. */
+	mintSideAttemptScope(): { scope: AttemptScope; dispose: () => void } {
+		return this.#attemptAuthority.mintSide();
+	}
+
+	/** Return the Agent-owned attempt scope authority for session record injection. */
+	getAttemptScopeAuthority() {
+		return this.#attemptAuthority;
+	}
 
 	streamFn: StreamFn;
 	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
@@ -1155,20 +1179,32 @@ export class Agent {
 	 * did not drain. The abandoned provider/tool stream may still settle later, so
 	 * #runLoop guards every state mutation with a run id.
 	 */
-	forceAbort(reason = "Force aborted"): boolean {
+	forceAbort(reason = "Force aborted", logicalRunId?: ManagedLogicalRunId | number): boolean {
+		const targetLogicalRunId = logicalRunId ?? this.#managedLogicalRunOwner ?? this.#activeRunId;
+		const handle = targetLogicalRunId !== undefined ? this.#runHandles.get(targetLogicalRunId) : undefined;
 		const runId = this.#activeRunId;
 		const managedLogicalRunId = this.#managedLogicalRunOwner;
+		const activeLogicalRunId = managedLogicalRunId ?? runId;
+		if (
+			targetLogicalRunId !== undefined &&
+			activeLogicalRunId !== undefined &&
+			activeLogicalRunId !== targetLogicalRunId
+		) {
+			throw new Error(`forceAbort: logicalRunId ${targetLogicalRunId} does not match the active run`);
+		}
+		const activeResourceDomain = this.#activeResourceCancellationDomain;
+		const activeResourceRunId = this.#activeResourceRunId;
 		const hadActiveRun = runId !== undefined && (this.#runningPrompt !== undefined || this.#state.isStreaming);
 		if (!hadActiveRun) return false;
 
 		this.#abortController?.abort(reason);
 		this.#continuationGeneration++;
+		this.#attemptAuthority.advanceMain();
 		this.#state.isStreaming = false;
 		this.#state.streamMessage = null;
 		this.#state.pendingToolCalls = new Set<string>();
 		this.#abortController = undefined;
 		this.#cursorToolResultBuffer = [];
-		this.resourceLedger.quarantine(this.#activeResourceRunId ?? String(managedLogicalRunId ?? runId));
 		this.#managedLogicalRunOwner = undefined;
 
 		const resolve = this.#resolveRunningPrompt;
@@ -1176,12 +1212,20 @@ export class Agent {
 		this.#resolveRunningPrompt = undefined;
 		this.#activeRunId = undefined;
 		this.#activeResourceRunId = undefined;
+		this.#activeResourceCancellationDomain = undefined;
 		resolve?.();
-		if (this.#activeFallbackManaged) {
-			this.requestRunTerminal(managedLogicalRunId ?? runId, { stopReason: "cancelled" });
-		} else {
-			this.#finalizeRun(runId, { type: "agent_end", messages: [] });
-		}
+		this.#finalizeRun(
+			activeLogicalRunId ?? runId!,
+			{
+				type: "agent_end",
+				messages: [],
+				stopReason: "cancelled",
+				scope: handle?.scope,
+			},
+			undefined,
+			activeResourceDomain,
+		);
+		if (activeResourceRunId) this.resourceLedger.quarantine(activeResourceRunId);
 		return true;
 	}
 
@@ -1218,6 +1262,8 @@ export class Agent {
 	 */
 	requestRunTerminal(logicalRunId: ManagedLogicalRunId, request: RunTerminalRequest): boolean {
 		if (this.#terminalizedLogicalRunIds.has(logicalRunId)) return false;
+		const handle = this.#runHandles.get(logicalRunId);
+		if (!handle) throw new Error(`requestRunTerminal: unknown logicalRunId ${logicalRunId} (no attempt handle)`);
 		if (this.#managedLogicalRunOwner === logicalRunId) {
 			this.#managedLogicalRunOwner = undefined;
 		}
@@ -1227,6 +1273,7 @@ export class Agent {
 				type: "agent_end",
 				messages: request.messages ?? [],
 				...(request.stopReason === "cancelled" ? { stopReason: "cancelled" as const } : {}),
+				scope: handle.scope,
 			},
 			() => {
 				for (const message of request.messages ?? []) {
@@ -1350,6 +1397,10 @@ export class Agent {
 		const model = this.#state.model;
 		if (!model) throw new Error("No model configured");
 
+		const maintenanceContinuation = options?.maintenanceContinuation === true;
+		if (maintenanceContinuation && this.#managedLogicalRunOwner === undefined) {
+			throw new Error("Maintenance continuation ownership is unavailable");
+		}
 		let skipInitialSteeringPoll = options?.skipInitialSteeringPoll === true;
 
 		const { promise, resolve } = Promise.withResolvers<void>();
@@ -1366,14 +1417,34 @@ export class Agent {
 		this.#state.error = undefined;
 
 		const fallbackManaged = options?.fallbackManaged === true;
-		const managedLogicalRunOwner = fallbackManaged ? (this.#managedLogicalRunOwner ?? runId) : undefined;
+		const managedLogicalRunOwner = fallbackManaged
+			? (this.#managedLogicalRunOwner ?? runId)
+			: maintenanceContinuation
+				? this.#managedLogicalRunOwner
+				: undefined;
+		const continuesLogicalRun = fallbackManaged || maintenanceContinuation;
 		const startsManagedLogicalRun = fallbackManaged && this.#managedLogicalRunOwner === undefined;
 		this.#activeResourceRunId = String(managedLogicalRunOwner ?? runId);
-		this.resourceLedger.open(this.#activeResourceRunId);
-		options?.onRunAccepted?.();
+		this.#activeResourceCancellationDomain = this.resourceLedger.open(this.#activeResourceRunId);
+		if (!this.#activeResourceCancellationDomain) {
+			this.#state.isStreaming = false;
+			this.#abortController = undefined;
+			this.#activeRunId = undefined;
+			this.#activeResourceRunId = undefined;
+			this.#activeResourceCancellationDomain = undefined;
+			this.#runningPrompt = undefined;
+			this.#resolveRunningPrompt = undefined;
+			resolve();
+			throw new Error("Prompt resource cancellation domain is unavailable");
+		}
+		const logicalRunId = managedLogicalRunOwner ?? runId;
+		const scope = this.#attemptAuthority.mintMain();
+		const handle: AttemptRunHandle = { logicalRunId, scope };
+		this.#runHandles.set(logicalRunId, handle);
+		options?.onRunAccepted?.(handle);
 		if (startsManagedLogicalRun) {
-			this.#managedLogicalRunOwner = managedLogicalRunOwner;
-			this.#emit({ type: "agent_start" });
+			this.#managedLogicalRunOwner = logicalRunId;
+			this.#emit({ type: "agent_start", scope });
 		}
 		if (fallbackManaged && this.#cursorToolResultBuffer.length > 0) {
 			const error = new ManagedCursorInvariantError(
@@ -1383,6 +1454,7 @@ export class Agent {
 			this.#abortController = undefined;
 			this.#activeRunId = undefined;
 			this.#activeResourceRunId = undefined;
+			this.#activeResourceCancellationDomain = undefined;
 			this.#runningPrompt = undefined;
 			this.#resolveRunningPrompt = undefined;
 			resolve();
@@ -1392,7 +1464,6 @@ export class Agent {
 		}
 		// Each run gets a fresh buffer only after managed stale-state validation.
 		this.#cursorToolResultBuffer = [];
-		this.#activeFallbackManaged = fallbackManaged;
 
 		const reasoning = this.#state.thinkingLevel;
 		const context: AgentContext = {
@@ -1476,12 +1547,16 @@ export class Agent {
 			preferWebsockets: this.#preferWebsockets,
 			convertToLlm: this.#convertToLlm,
 			transformContext: this.#transformContext,
+			attemptMinter: { mint: () => this.#attemptAuthority.mintMain() },
+			initialScope: scope,
 			onPayload: this.#onPayload,
 			onResponse: this.#onResponse,
 			onSseEvent: this.#onSseEvent,
 			signal: abortController.signal,
 			resourceLedger: this.resourceLedger,
 			resourceRunId: this.#activeResourceRunId,
+			resourceCancellationDomain: this.#activeResourceCancellationDomain,
+			resourceSealOwner: "caller",
 			getApiKey: this.getApiKey,
 			getAuthCredentialType: this.getAuthCredentialType,
 			getToolContext: this.#getToolContext,
@@ -1575,8 +1650,8 @@ export class Agent {
 
 		try {
 			const stream = messages
-				? agentLoop(messages, context, config, abortController.signal, this.streamFn, !fallbackManaged)
-				: agentLoopContinue(context, config, abortController.signal, this.streamFn, !fallbackManaged);
+				? agentLoop(messages, context, config, abortController.signal, this.streamFn, !continuesLogicalRun, scope)
+				: agentLoopContinue(context, config, abortController.signal, this.streamFn, !continuesLogicalRun, scope);
 
 			for await (const event of stream) {
 				if (this.#activeRunId !== runId) {
@@ -1636,7 +1711,13 @@ export class Agent {
 						}
 						this.#state.isStreaming = false;
 						this.#state.streamMessage = null;
-						if (event.stopReason === "maintenance") {
+						// A maintenance checkpoint is only non-terminal while a continuation will
+						// follow. An aborted maintenance yields none, and because the loop runs with
+						// `resourceSealOwner: "caller"` it deliberately leaves sealing to us, so
+						// treating it as a checkpoint here would leave the run open forever and make
+						// every cancel report `run_not_sealed`.
+						if (event.stopReason === "maintenance" && event.maintenanceOutcome !== "aborted") {
+							this.#managedLogicalRunOwner ??= managedLogicalRunOwner ?? runId;
 							maintenanceInterrupted = true;
 							this.#emit(event);
 							continue;
@@ -1716,12 +1797,32 @@ export class Agent {
 			) {
 				continuation = managedDecision.continuation;
 			}
-			const ownership: ManagedAttemptContinuationOwnership = {
-				runId,
-				logicalRunId: managedLogicalRunOwner ?? runId,
-				generation: continuationGeneration,
-				isCurrent: () => this.#continuationGeneration === continuationGeneration && this.#activeRunId === undefined,
-			};
+			const domain = this.#activeResourceCancellationDomain;
+			const continuationReservation =
+				continuation && domain
+					? this.resourceLedger.reserveProducer(
+							String(managedLogicalRunOwner ?? runId),
+							domain,
+							"post_prompt",
+							"managed-continuation",
+						)
+					: undefined;
+			if (continuation && !continuationReservation?.ok) {
+				this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: "error" });
+				continuation = undefined;
+			}
+			const ownership: ManagedAttemptContinuationOwnership | undefined = continuationReservation?.ok
+				? {
+						runId,
+						logicalRunId: managedLogicalRunOwner ?? runId,
+						generation: continuationGeneration,
+						domain: continuationReservation.lease.domain,
+						lease: continuationReservation.lease,
+						handle,
+						isCurrent: () =>
+							this.#continuationGeneration === continuationGeneration && this.#activeRunId === undefined,
+					}
+				: undefined;
 			if (this.#activeRunId === runId) {
 				this.#state.isStreaming = false;
 				this.#state.streamMessage = null;
@@ -1729,20 +1830,20 @@ export class Agent {
 				this.#abortController = undefined;
 				this.#activeRunId = undefined;
 				this.#activeResourceRunId = undefined;
-				this.#activeFallbackManaged = false;
+				this.#activeResourceCancellationDomain = undefined;
 				this.#resolveRunningPrompt?.();
 				this.#runningPrompt = undefined;
 				this.#resolveRunningPrompt = undefined;
 			}
 			if (
-				fallbackManaged &&
+				continuesLogicalRun &&
 				!continuation &&
 				!maintenanceInterrupted &&
 				this.#managedLogicalRunOwner === managedLogicalRunOwner
 			) {
 				this.#managedLogicalRunOwner = undefined;
 			}
-			if (continuation && ownership.isCurrent()) {
+			if (continuation && ownership?.isCurrent()) {
 				try {
 					await continuation(ownership);
 					if (
@@ -1765,6 +1866,8 @@ export class Agent {
 						this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: "error" });
 						if (this.#managedLogicalRunOwner === managedLogicalRunOwner) this.#managedLogicalRunOwner = undefined;
 					}
+				} finally {
+					ownership.lease.closeDiscovery();
 				}
 			}
 		}
@@ -1781,18 +1884,48 @@ export class Agent {
 		logicalRunId: ManagedLogicalRunId,
 		event?: Extract<AgentEvent, { type: "agent_end" }>,
 		beforeEvent?: () => void,
+		knownDomain?: RunCancellationDomain,
 	): void {
 		if (this.#terminalizedLogicalRunIds.has(logicalRunId)) return;
+		const handle = this.#runHandles.get(logicalRunId);
+		if (!handle && !event?.scope) {
+			throw new Error(`finalizeRun: unknown logicalRunId ${logicalRunId} (no attempt handle)`);
+		}
+		const resourceRunId = String(logicalRunId);
+		const boundDomain = this.resourceLedger.lookupDomain(resourceRunId);
+		const domain = boundDomain ?? knownDomain;
+		const terminalReservation = boundDomain
+			? this.resourceLedger.reserveProducer(resourceRunId, boundDomain, "post_prompt", "terminal-publication")
+			: undefined;
 		this.#terminalizedLogicalRunIds.add(logicalRunId);
 		if (this.#terminalizedLogicalRunIds.size > 256) {
 			this.#terminalizedLogicalRunIds.delete(this.#terminalizedLogicalRunIds.values().next().value!);
 		}
+		const terminalEvent: Extract<AgentEvent, { type: "agent_end" }> = event ?? {
+			type: "agent_end",
+			messages: [],
+			scope: handle?.scope,
+		};
+		if (handle) terminalEvent.scope = handle.scope;
+		if (domain) {
+			setAgentTerminalOwnerContext(terminalEvent, {
+				resourceRunId,
+				domain,
+			});
+		}
 		try {
 			beforeEvent?.();
-			if (event) this.#emit(event);
+			this.#emit(terminalEvent);
 		} finally {
-			// Publish terminal lifecycle synchronously before sealing the stable handle.
-			this.resourceLedger.seal(String(logicalRunId));
+			try {
+				terminalReservation?.ok && terminalReservation.lease.closeDiscovery();
+			} finally {
+				try {
+					this.resourceLedger.seal(resourceRunId);
+				} finally {
+					this.#runHandles.delete(logicalRunId);
+				}
+			}
 		}
 	}
 

package/src/attempt-scope.ts

@@ -0,0 +1,195 @@
+/**
+ * Per-attempt scope identity for request-scoped execution attribution.
+ *
+ * An AttemptScope is an immutable, frozen value allocated before every
+ * observable lifecycle emission for a single provider/agent attempt.
+ * It carries a stable `attemptId`, a monotonic `generation` (per-lineage),
+ * and a `lineage` discriminator that distinguishes the main attempt from
+ * concurrent side attempts (IRC background, ephemeral/btw turns).
+ *
+ * The `attemptId` + `generation` + `lineage` form the comparable identity.
+ * AttemptScope is structurally assignable to AttemptScopeRef in
+ * `packages/ai` so it can be carried through `SimpleStreamOptions` and
+ * provider hook signatures without a reverse dependency.
+ */
+export type AttemptLineage = "main" | `side:${string}`;
+
+export interface AttemptScope {
+	readonly attemptId: string;
+	readonly generation: number;
+	readonly lineage: AttemptLineage;
+}
+
+export function attemptScopesEqual(a: AttemptScope, b: AttemptScope): boolean {
+	return a.attemptId === b.attemptId && a.generation === b.generation && a.lineage === b.lineage;
+}
+
+/**
+ * Per-lineage currentness authority. Main and side attempts have separate
+ * instances so a side attempt never invalidates the main scope, and
+ * `forceAbort` advances only the main lineage.
+ */
+export interface LineageCurrentness {
+	readonly lineage: AttemptLineage;
+	/** True iff no successor scope with a greater generation was allocated in this lineage. */
+	isCurrent(scope: AttemptScope): boolean;
+	/** Allocate the next generation for the given attempt identity in this lineage. */
+	advance(attemptId: string): number;
+	/** Allocate the next generation in this lineage. */
+	/** Current generation value for this lineage. */
+	readonly current: number;
+}
+
+export function createLineageCurrentness(lineage: AttemptLineage): LineageCurrentness {
+	let current = 0;
+	let currentAttemptId: string | undefined;
+	return {
+		lineage,
+		get current() {
+			return current;
+		},
+		isCurrent(scope: AttemptScope): boolean {
+			return scope.lineage === lineage && scope.generation === current && scope.attemptId === currentAttemptId;
+		},
+		advance(attemptId: string): number {
+			currentAttemptId = attemptId;
+			return ++current;
+		},
+	};
+}
+
+/**
+ * Agent-owned authority over all attempt lineages. Owns the main lineage;
+ * side lineages are registered/removed with bounded lifecycle.
+ *
+ * This is the SINGLE source of currentness truth injected into
+ * AttemptRecordStore (packages/coding-agent). Every store operation
+ * calls `authority.isCurrent(scope)` and fails closed when the authority
+ * is missing or the scope is superseded.
+ */
+export interface AttemptScopeAuthority {
+	/** Register a side-lineage authority. Returns an unregister function. */
+	registerSide(lineage: AttemptLineage, auth: LineageCurrentness): () => void;
+	/** True iff the scope's lineage is known and its generation is current. */
+	isCurrent(scope: AttemptScope): boolean;
+	/** Advance the main lineage (called by forceAbort). Returns the new generation. */
+	advanceMain(): number;
+	/** Mint the next main-lineage scope. */
+	mintMain(): AttemptScope;
+	/**
+	 * Atomically register a fresh side lineage, mint a side scope, and return
+	 * both the scope and a dispose function. The authority knows the lineage
+	 * BEFORE the scope is returned, so `isCurrent` succeeds immediately.
+	 */
+	mintSide(): { scope: AttemptScope; dispose: () => void };
+}
+
+export interface AttemptMinter {
+	mint(lineage: AttemptLineage): AttemptScope;
+}
+
+export function createAttemptMinter(): AttemptMinter {
+	const generations = new Map<AttemptLineage, number>();
+	return {
+		mint(lineage: AttemptLineage): AttemptScope {
+			const gen = (generations.get(lineage) ?? 0) + 1;
+			generations.set(lineage, gen);
+			return Object.freeze({
+				attemptId: crypto.randomUUID(),
+				generation: gen,
+				lineage,
+			});
+		},
+	};
+}
+
+const SIDE_LRU_CAP = 1024;
+
+/**
+ * Create the Agent-owned authority. Owns the main lineage and a bounded
+ * (LRU-capped) map of side lineages. Only RETIRED side authorities are
+ * eligible for LRU eviction; a live side attempt is never silently
+ * invalidated by a newer side registration.
+ */
+export function createAttemptScopeAuthority(): AttemptScopeAuthority {
+	const mainAuth = createLineageCurrentness("main");
+	const sideAuths = new Map<AttemptLineage, LineageCurrentness>();
+	const sideOrder: AttemptLineage[] = [];
+	const retiredSet = new Set<AttemptLineage>();
+
+	function evictRetiredIfNeeded(): void {
+		// Only evict RETIRED side authorities. A live side attempt is never
+		// evicted by a newer registration.
+		while (sideOrder.length > SIDE_LRU_CAP) {
+			const retiredIdx = sideOrder.findIndex(l => retiredSet.has(l));
+			if (retiredIdx < 0) break;
+			const [removed] = sideOrder.splice(retiredIdx, 1);
+			if (removed) {
+				sideAuths.delete(removed);
+				retiredSet.delete(removed);
+			}
+		}
+	}
+
+	function mintFor(lineage: AttemptLineage, auth: LineageCurrentness): AttemptScope {
+		const attemptId = crypto.randomUUID();
+		return Object.freeze({
+			attemptId,
+			generation: auth.advance(attemptId),
+			lineage,
+		});
+	}
+
+	return {
+		registerSide(lineage: AttemptLineage, auth: LineageCurrentness): () => void {
+			if (sideAuths.has(lineage)) {
+				const idx = sideOrder.indexOf(lineage);
+				if (idx >= 0) sideOrder.splice(idx, 1);
+			}
+			sideAuths.set(lineage, auth);
+			sideOrder.push(lineage);
+			evictRetiredIfNeeded();
+			return () => {
+				if (sideAuths.get(lineage) === auth) {
+					// Mark as retired but keep in maps until eviction.
+					// isCurrent returns false for retired lineages because
+					// the auth is still present but the scope is superseded
+					// by disposal (generation stays at its last value).
+					retiredSet.add(lineage);
+					evictRetiredIfNeeded();
+				}
+			};
+		},
+		isCurrent(scope: AttemptScope): boolean {
+			if (scope.lineage === "main") return mainAuth.isCurrent(scope);
+			if (retiredSet.has(scope.lineage)) return false;
+			const auth = sideAuths.get(scope.lineage);
+			return auth ? auth.isCurrent(scope) : false;
+		},
+		advanceMain(): number {
+			// Advance main lineage to a fresh attemptId so any previously-minted
+			// main scope becomes non-current. The next mintMain() will set the
+			// real attemptId for the new attempt.
+			return mainAuth.advance(crypto.randomUUID());
+		},
+		mintMain(): AttemptScope {
+			return mintFor("main", mainAuth);
+		},
+		mintSide(): { scope: AttemptScope; dispose: () => void } {
+			const lineage = `side:${crypto.randomUUID()}` as AttemptLineage;
+			const auth = createLineageCurrentness(lineage);
+			const unregister = this.registerSide(lineage, auth);
+			const scope = mintFor(lineage, auth);
+			return { scope, dispose: unregister };
+		},
+	};
+}
+
+/**
+ * Immutable per-run attempt handle, carried through terminal/finalizer paths.
+ * Keyed by logicalRunId in the Agent's `#runHandles` map.
+ */
+export interface AttemptRunHandle {
+	readonly logicalRunId: number | import("./types.js").ManagedLogicalRunId;
+	readonly scope: AttemptScope;
+}

package/src/proxy.ts

@@ -387,7 +387,7 @@ function processProxyEvent(
 					partial,
 				};
 			}
-			return undefined;
+			throw new Error("Received toolcall_end for non-toolCall content");
 		}
 
 		case "done":