@gajae-code/agent-core 0.12.4 → 0.12.6

package/src/run-resource-ledger.ts

@@ -1,7 +1,17 @@
-import type { RunResourceEntry, RunResourceLedger, RunSettlementProof } from "./types";
+import type {
+	ClaimProducerResult,
+	ForkProducerResult,
+	ReserveProducerResult,
+	RunCancellationDomain,
+	RunCancellationDomainBridge,
+	RunResourceEntry,
+	RunResourceKind,
+	RunResourceLedger,
+	RunResourceProducerLease,
+	RunSettlementProof,
+} from "./types";
 
 const MAX_TOMBSTONE_ENTRIES = 256;
-
 type RunLifecycle = "open" | "sealed" | "quarantined";
 
 interface TrackedResource {
@@ -10,10 +20,14 @@ interface TrackedResource {
 
 interface RunState {
 	lifecycle: RunLifecycle;
+	resourceRunId: string;
+	domain: RunCancellationDomain | undefined;
+	domainBridge: RunCancellationDomainBridge;
 	resources: Map<string, TrackedResource>;
-	/** Bounded public snapshot retained after quarantine. */
 	tombstone: RunResourceEntry[];
 	waiters: Set<SettlementWaiter>;
+	claimedOwners: Set<object>;
+	released: boolean;
 }
 
 interface SettlementWaiter {
@@ -27,63 +41,93 @@ function copyEntries(entries: readonly RunResourceEntry[]): RunResourceEntry[] {
 
 export function createRunResourceLedger(): RunResourceLedger {
 	const runs = new Map<string, RunState>();
+	const standaloneDomains = new Map<string, { domain: RunCancellationDomain; controller: AbortController }>();
+	const standaloneReleased = new Set<string>();
+	const standaloneQuarantined = new Set<string>();
+	let bridge: RunCancellationDomainBridge | undefined;
+	let agentSessionClaimKey: object | undefined;
 	let sequence = 0;
 
-	const snapshot = (state: RunState): RunResourceEntry[] => {
-		if (state.lifecycle === "quarantined") return copyEntries(state.tombstone);
-		return [...state.resources.values()].map(resource => ({ ...resource.entry }));
+	const standaloneBridge: RunCancellationDomainBridge = {
+		open(resourceRunId) {
+			if (standaloneQuarantined.has(resourceRunId)) return { ok: false, reason: "quarantined" };
+			const existing = standaloneDomains.get(resourceRunId);
+			if (existing) return { ok: true, domain: existing.domain, created: false };
+			if (standaloneReleased.has(resourceRunId)) return { ok: false, reason: "duplicate_identity" };
+			const controller = new AbortController();
+			const domain: RunCancellationDomain = { resourceRunId, signal: controller.signal };
+			standaloneDomains.set(resourceRunId, { domain, controller });
+			return { ok: true, domain, created: true };
+		},
+		lookup(resourceRunId) {
+			return standaloneDomains.get(resourceRunId)?.domain;
+		},
+		abort(resourceRunId, reason) {
+			const record = standaloneDomains.get(resourceRunId);
+			if (!record)
+				return { ok: false, reason: standaloneQuarantined.has(resourceRunId) ? "quarantined" : "unknown_run" };
+			const newlyAborted = !record.controller.signal.aborted;
+			if (newlyAborted) record.controller.abort(reason);
+			return { ok: true, newlyAborted };
+		},
+		release(resourceRunId, disposition) {
+			const record = standaloneDomains.get(resourceRunId);
+			if (!record) return;
+			if (disposition === "quarantined") {
+				standaloneQuarantined.add(resourceRunId);
+				if (!record.controller.signal.aborted) record.controller.abort();
+			}
+			standaloneDomains.delete(resourceRunId);
+			standaloneReleased.add(resourceRunId);
+		},
 	};
 
+	const snapshot = (state: RunState): RunResourceEntry[] =>
+		state.lifecycle === "quarantined"
+			? copyEntries(state.tombstone)
+			: [...state.resources.values()].map(resource => ({ ...resource.entry }));
+
 	const settlementProof = (state: RunState): RunSettlementProof | undefined => {
-		if (state.lifecycle === "quarantined") {
-			return { status: "unfenced", pending: copyEntries(state.tombstone) };
-		}
-		if (state.lifecycle === "sealed" && state.resources.size === 0) {
-			return { status: "settled" };
-		}
+		if (state.lifecycle === "quarantined")
+			return { status: "unfenced", reason: "quarantined", pending: copyEntries(state.tombstone) };
+		if (state.lifecycle === "sealed" && state.resources.size === 0) return { status: "settled" };
 		return undefined;
 	};
 
-	const removeWaiter = (state: RunState, waiter: SettlementWaiter): void => {
-		clearTimeout(waiter.timer);
-		state.waiters.delete(waiter);
+	const releaseIfSettled = (state: RunState): void => {
+		if (state.released || state.lifecycle !== "sealed" || state.resources.size !== 0 || !state.domain) return;
+		state.released = true;
+		state.domainBridge.release(state.resourceRunId, "settled");
+		state.domain = undefined;
 	};
 
 	const notify = (state: RunState): void => {
 		const proof = settlementProof(state);
-		if (!proof) return;
-		for (const waiter of state.waiters) {
-			removeWaiter(state, waiter);
-			waiter.resolve(
-				proof.status === "unfenced"
-					? { status: "unfenced", pending: copyEntries(proof.pending) }
-					: { status: "settled" },
-			);
+		if (proof) {
+			for (const waiter of [...state.waiters]) {
+				clearTimeout(waiter.timer);
+				state.waiters.delete(waiter);
+				waiter.resolve(
+					proof.status === "settled"
+						? proof
+						: { status: "unfenced", reason: proof.reason, pending: copyEntries(proof.pending) },
+				);
+			}
 		}
+		releaseIfSettled(state);
 	};
 
-	const settleTracked = (state: RunState, id: string): void => {
-		if (!state.resources.delete(id)) return;
-		notify(state);
+	const appendTombstone = (state: RunState, entry: RunResourceEntry): void => {
+		state.tombstone.push({ ...entry });
+		if (state.tombstone.length > MAX_TOMBSTONE_ENTRIES)
+			state.tombstone.splice(0, state.tombstone.length - MAX_TOMBSTONE_ENTRIES);
 	};
 
 	const observeSettlement = (settled: PromiseLike<unknown>, onSettled: () => void): void => {
-		// Assimilate the settlement promise once and consume both outcomes so a
-		// rejected resource cannot become an unhandled rejection.
-		let promise: Promise<unknown>;
 		try {
-			promise = Promise.resolve(settled);
+			void Promise.resolve(settled).then(onSettled, onSettled);
 		} catch {
 			onSettled();
-			return;
-		}
-		void promise.then(onSettled, onSettled);
-	};
-
-	const appendTombstone = (state: RunState, entry: RunResourceEntry): void => {
-		state.tombstone.push({ ...entry });
-		if (state.tombstone.length > MAX_TOMBSTONE_ENTRIES) {
-			state.tombstone.splice(0, state.tombstone.length - MAX_TOMBSTONE_ENTRIES);
 		}
 	};
 
@@ -93,87 +137,184 @@ export function createRunResourceLedger(): RunResourceLedger {
 			state.tombstone = [];
 			for (const resource of state.resources.values()) appendTombstone(state, resource.entry);
 			state.resources.clear();
+			if (state.domain) {
+				state.domainBridge.abort(state.resourceRunId);
+				if (!state.released) {
+					state.released = true;
+					state.domainBridge.release(state.resourceRunId, "quarantined");
+				}
+				state.domain = undefined;
+			}
 		}
 		notify(state);
 		return copyEntries(state.tombstone);
 	};
 
+	const register = (
+		state: RunState,
+		kind: RunResourceKind,
+		label: string,
+		settled: PromiseLike<unknown>,
+	): string | undefined => {
+		if (state.lifecycle === "quarantined") {
+			const entry: RunResourceEntry = { id: `${++sequence}`, kind, label, registeredAt: Date.now() };
+			appendTombstone(state, entry);
+			observeSettlement(settled, () => {});
+			return undefined;
+		}
+		// Sealing only freezes admission of genuinely *new* work through
+		// reserveProducer()/claimProducer(); it does not mean the run's resources have
+		// all been registered yet. `agent_end` is published before seal(), and its
+		// handlers register their own post-prompt work while the event is still
+		// draining, so this late registration is the normal lifecycle rather than an
+		// escaped resource. Admit it into ordinary settlement accounting so the run
+		// stays unsettled until it completes; quarantining here would make every
+		// cancel unfenced forever.
+		const entry: RunResourceEntry = { id: `${++sequence}`, kind, label, registeredAt: Date.now() };
+		state.resources.set(entry.id, { entry });
+		observeSettlement(settled, () => {
+			state.resources.delete(entry.id);
+			notify(state);
+		});
+		return entry.id;
+	};
+
+	const leaseFor = (state: RunState, kind: RunResourceKind, label: string): RunResourceProducerLease | undefined => {
+		const domain = state.domain;
+		if (!domain) return undefined;
+		const completion = Promise.withResolvers<void>();
+		if (!register(state, kind, label, completion.promise)) return undefined;
+		let closed = false;
+		const close = (): void => {
+			if (closed) return;
+			closed = true;
+			completion.resolve();
+		};
+		const lease: RunResourceProducerLease = {
+			resourceRunId: state.resourceRunId,
+			domain,
+			signal: domain.signal,
+			track(childKind, childLabel, settled) {
+				if (closed || state.lifecycle === "quarantined") {
+					quarantineState(state);
+					observeSettlement(settled, () => {});
+					return false;
+				}
+				return register(state, childKind, childLabel, settled) !== undefined;
+			},
+			fork(expectedDomain, childKind, childLabel): ForkProducerResult {
+				if (expectedDomain !== domain) {
+					quarantineState(state);
+					return { ok: false, reason: "domain_mismatch" };
+				}
+				const wasQuarantined = state.lifecycle === "quarantined";
+				if (closed || wasQuarantined) {
+					quarantineState(state);
+					return { ok: false, reason: wasQuarantined ? "quarantined" : "parent_closed" };
+				}
+				const child = leaseFor(state, childKind, childLabel);
+				return child ? { ok: true, lease: child } : { ok: false, reason: "quarantined" };
+			},
+			closeDiscovery: close,
+		};
+		return lease;
+	};
+
 	return {
+		bindCancellationDomainBridge(nextBridge) {
+			if (bridge && bridge !== nextBridge) throw new Error("Run cancellation domain bridge is already bound");
+			bridge = nextBridge;
+		},
+		bindAgentSessionClaimKey(key) {
+			if (agentSessionClaimKey && agentSessionClaimKey !== key) {
+				throw new Error("AgentSession claim key is already bound");
+			}
+			agentSessionClaimKey = key;
+		},
 		open(resourceRunId) {
 			const existing = runs.get(resourceRunId);
-			if (existing) return;
-			runs.set(resourceRunId, {
+			if (existing) return existing.lifecycle === "open" ? existing.domain : undefined;
+			const domainBridge = bridge ?? standaloneBridge;
+			const opened = domainBridge.open(resourceRunId);
+			if (!opened.ok) return undefined;
+			const state: RunState = {
 				lifecycle: "open",
-				resources: new Map<string, TrackedResource>(),
+				resourceRunId,
+				domain: opened.domain,
+				domainBridge,
+				resources: new Map(),
 				tombstone: [],
-				waiters: new Set<SettlementWaiter>(),
-			});
+				waiters: new Set(),
+				claimedOwners: new Set(),
+				released: false,
+			};
+			runs.set(resourceRunId, state);
+			return opened.domain;
+		},
+		lookupDomain(resourceRunId) {
+			return runs.get(resourceRunId)?.domain;
+		},
+		reserveProducer(resourceRunId, expectedDomain, kind, label): ReserveProducerResult {
+			const state = runs.get(resourceRunId);
+			if (!state) return { ok: false, reason: "unknown_run" };
+			if (state.lifecycle === "quarantined") return { ok: false, reason: "quarantined" };
+			if (state.lifecycle !== "open") {
+				quarantineState(state);
+				return { ok: false, reason: "sealed" };
+			}
+			if (expectedDomain && expectedDomain !== state.domain) {
+				quarantineState(state);
+				return { ok: false, reason: "domain_mismatch" };
+			}
+			const lease = leaseFor(state, kind, label);
+			return lease ? { ok: true, lease } : { ok: false, reason: "quarantined" };
+		},
+		claimProducer(resourceRunId, expectedDomain, ownerKey): ClaimProducerResult {
+			if (!agentSessionClaimKey || ownerKey !== agentSessionClaimKey) {
+				return { ok: false, reason: "closed" };
+			}
+			const state = runs.get(resourceRunId);
+			if (!state) return { ok: false, reason: "handle_mismatch" };
+			if (state.lifecycle === "quarantined") return { ok: false, reason: "quarantined" };
+			if (state.lifecycle !== "open") {
+				quarantineState(state);
+				return { ok: false, reason: "closed" };
+			}
+			if (expectedDomain && expectedDomain !== state.domain) {
+				quarantineState(state);
+				return { ok: false, reason: "domain_mismatch" };
+			}
+			if (state.claimedOwners.has(ownerKey)) {
+				quarantineState(state);
+				return { ok: false, reason: "already_claimed" };
+			}
+			state.claimedOwners.add(ownerKey);
+			const lease = leaseFor(state, "post_prompt", "agent-session");
+			return lease ? { ok: true, lease } : { ok: false, reason: "quarantined" };
 		},
-
 		track(resourceRunId, kind, label, settled) {
-			let state = runs.get(resourceRunId);
+			const state = runs.get(resourceRunId);
 			if (!state) {
-				// Keep track() usable for low-level callers while making the lifecycle
-				// explicit for settlement: an implicitly-created run is still open and
-				// therefore cannot settle until seal() is called.
-				state = {
-					lifecycle: "open",
-					resources: new Map<string, TrackedResource>(),
-					tombstone: [],
-					waiters: new Set<SettlementWaiter>(),
-				};
-				runs.set(resourceRunId, state);
-			}
-
-			const id = `${++sequence}`;
-			const entry: RunResourceEntry = { id, kind, label, registeredAt: Date.now() };
-
-			if (state.lifecycle === "quarantined") {
-				// Quarantine is terminal: late work is retained only in the bounded
-				// tombstone and never re-enters normal settlement accounting.
-				appendTombstone(state, entry);
 				observeSettlement(settled, () => {});
 				return;
 			}
-
-			if (state.lifecycle === "sealed") {
-				// Sealing only freezes admission of *new* work; it does not mean the run's
-				// resources have all been registered yet. `agent_end` is published before
-				// seal(), and its handlers register their own post-prompt work while the
-				// event is still draining, so this late registration is the normal
-				// lifecycle rather than an escaped resource. Admit it into ordinary
-				// settlement accounting so the run stays unsettled until it completes;
-				// quarantining here would make every cancel unfenced forever.
-				state.resources.set(id, { entry });
-				observeSettlement(settled, () => settleTracked(state!, id));
-				return;
-			}
-
-			state.resources.set(id, { entry });
-			observeSettlement(settled, () => settleTracked(state!, id));
+			register(state, kind, label, settled);
 		},
-
 		pending(resourceRunId) {
 			const state = runs.get(resourceRunId);
 			return state ? snapshot(state) : [];
 		},
-
 		seal(resourceRunId) {
 			const state = runs.get(resourceRunId);
 			if (state?.lifecycle !== "open") return;
 			state.lifecycle = "sealed";
 			notify(state);
 		},
-
 		waitForSettlement(resourceRunId, { graceMs }) {
 			const state = runs.get(resourceRunId);
-			if (!state) {
-				return Promise.resolve({ status: "unfenced", pending: [] });
-			}
-
+			if (!state) return Promise.resolve({ status: "unfenced", reason: "unknown_run", pending: [] });
 			const immediate = settlementProof(state);
 			if (immediate) return Promise.resolve(immediate);
-
 			const { promise, resolve } = Promise.withResolvers<RunSettlementProof>();
 			let waiter!: SettlementWaiter;
 			waiter = {
@@ -185,6 +326,7 @@ export function createRunResourceLedger(): RunResourceLedger {
 						resolve(
 							settled ?? {
 								status: "unfenced",
+								reason: state.lifecycle === "open" ? "run_not_sealed" : "resources_pending",
 								pending: snapshot(state),
 							},
 						);
@@ -195,19 +337,9 @@ export function createRunResourceLedger(): RunResourceLedger {
 			state.waiters.add(waiter);
 			return promise;
 		},
-
 		quarantine(resourceRunId) {
-			let state = runs.get(resourceRunId);
-			if (!state) {
-				state = {
-					lifecycle: "quarantined",
-					resources: new Map<string, TrackedResource>(),
-					tombstone: [],
-					waiters: new Set<SettlementWaiter>(),
-				};
-				runs.set(resourceRunId, state);
-			}
-			return quarantineState(state);
+			const state = runs.get(resourceRunId);
+			return state ? quarantineState(state) : [];
 		},
 	};
 }

package/src/telemetry.ts

@@ -1687,9 +1687,9 @@ export async function instrumentedCompleteSimple<TApi extends Api>(
 	// for the cost / gateway hooks without stealing them from the caller.
 	let capturedHeaders: Readonly<Record<string, string>> | undefined;
 	const userOnResponse = options.onResponse;
-	const captureOnResponse: NonNullable<SimpleStreamOptions["onResponse"]> = (response, modelInfo) => {
+	const captureOnResponse: NonNullable<SimpleStreamOptions["onResponse"]> = (response, modelInfo, scope) => {
 		capturedHeaders = response.headers;
-		return userOnResponse?.(response, modelInfo);
+		return userOnResponse?.(response, modelInfo, scope);
 	};
 
 	try {

package/src/types.ts

@@ -17,6 +17,7 @@ import type {
 	TSchema,
 } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
+import type { AttemptMinter, AttemptRunHandle, AttemptScope } from "./attempt-scope";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
@@ -38,11 +39,91 @@ export interface RunResourceEntry {
 	registeredAt: number;
 }
 
-export type RunSettlementProof = { status: "settled" } | { status: "unfenced"; pending: RunResourceEntry[] };
+export type RunSettlementReason = "unknown_run" | "run_not_sealed" | "resources_pending" | "quarantined";
+export type RunSettlementProof =
+	| { status: "settled" }
+	| { status: "unfenced"; reason: RunSettlementReason; pending: RunResourceEntry[] };
+
+export interface RunCancellationDomain {
+	readonly resourceRunId: string;
+	readonly signal: AbortSignal;
+}
+
+export interface RunCancellationDomainBridge {
+	open(
+		resourceRunId: string,
+	):
+		| { ok: true; domain: RunCancellationDomain; created: boolean }
+		| { ok: false; reason: "duplicate_identity" | "quarantined" };
+	lookup(resourceRunId: string): RunCancellationDomain | undefined;
+	abort(
+		resourceRunId: string,
+		reason?: unknown,
+	): { ok: true; newlyAborted: boolean } | { ok: false; reason: "unknown_run" | "quarantined" };
+	release(resourceRunId: string, disposition: "settled" | "quarantined"): void;
+}
+
+export type ReserveProducerResult =
+	| { ok: true; lease: RunResourceProducerLease }
+	| { ok: false; reason: "unknown_run" | "sealed" | "quarantined" | "domain_mismatch" };
+export type ClaimProducerResult =
+	| { ok: true; lease: RunResourceProducerLease }
+	| { ok: false; reason: "already_claimed" | "handle_mismatch" | "domain_mismatch" | "closed" | "quarantined" };
+export type ForkProducerResult =
+	| { ok: true; lease: RunResourceProducerLease }
+	| { ok: false; reason: "parent_closed" | "quarantined" | "domain_mismatch" };
+
+export interface RunResourceProducerLease {
+	readonly resourceRunId: string;
+	readonly domain: RunCancellationDomain;
+	readonly signal: AbortSignal;
+	track(kind: RunResourceKind, label: string, settled: PromiseLike<unknown>): boolean;
+	fork(expectedDomain: RunCancellationDomain, kind: RunResourceKind, label: string): ForkProducerResult;
+	closeDiscovery(): void;
+}
+
+export interface AgentTerminalOwnerContext {
+	readonly resourceRunId: string;
+	readonly domain: RunCancellationDomain;
+}
+
+const terminalOwnerContexts = new WeakMap<object, AgentTerminalOwnerContext>();
+
+export function setAgentTerminalOwnerContext(event: object, context: AgentTerminalOwnerContext): void {
+	terminalOwnerContexts.set(event, context);
+}
+
+export function getAgentTerminalOwnerContext(event: object): AgentTerminalOwnerContext | undefined {
+	return terminalOwnerContexts.get(event);
+}
+export interface StandaloneRunOwnership {
+	readonly resourceRunId: string;
+	readonly domain: RunCancellationDomain;
+	claimContinuation():
+		| { ok: true; ownership: StandaloneRunOwnership }
+		| { ok: false; reason: "already_claimed" | "terminal" | "quarantined" };
+	abandon(reason: "cancelled" | "error"): void;
+}
 
 export interface RunResourceLedger {
+	/** Bind the bridge once, before any logical run may be opened. */
+	bindCancellationDomainBridge(bridge: RunCancellationDomainBridge): void;
+	/** Bind the unforgeable AgentSession claim key once, before terminal publication. */
+	bindAgentSessionClaimKey(key: object): void;
 	/** Reserve a run handle before publishing its `agent_start` event. */
-	open(resourceRunId: string): void;
+	open(resourceRunId: string): RunCancellationDomain | undefined;
+	lookupDomain(resourceRunId: string): RunCancellationDomain | undefined;
+	reserveProducer(
+		resourceRunId: string,
+		expectedDomain: RunCancellationDomain | undefined,
+		kind: RunResourceKind,
+		label: string,
+	): ReserveProducerResult;
+	claimProducer(
+		resourceRunId: string,
+		expectedDomain: RunCancellationDomain | undefined,
+		ownerKey: object,
+	): ClaimProducerResult;
 	track(resourceRunId: string, kind: RunResourceKind, label: string, settled: PromiseLike<unknown>): void;
 	pending(resourceRunId: string): RunResourceEntry[];
 	/** Seal a run after terminal event publication; only sealed empty runs settle. */
@@ -73,6 +154,10 @@ export interface ManagedAttemptContinuationOwnership {
 	/** Stable managed logical-run id; use for all terminal completion requests. */
 	readonly logicalRunId: ManagedLogicalRunId;
 	readonly generation: number;
+	readonly domain: RunCancellationDomain;
+	readonly lease: RunResourceProducerLease;
+	/** Immutable per-attempt handle used by terminalizers and continuations. */
+	readonly handle: AttemptRunHandle;
 	isCurrent(): boolean;
 }
 
@@ -94,9 +179,10 @@ export type ManagedAttemptOutcome =
 				/** Exact provider transport facts, including retry headers, for fallback policy. */
 				transportFailure?: TransportFailureFacts;
 			};
+			scope?: AttemptScope;
 	  }
-	| { type: "context_overflow_discarded"; message: AssistantMessage }
-	| { type: "run_terminal"; reason: "cancelled" | "error" | "exhausted" };
+	| { type: "context_overflow_discarded"; message: AssistantMessage; scope?: AttemptScope }
+	| { type: "run_terminal"; reason: "cancelled" | "error" | "exhausted"; scope?: AttemptScope };
 
 export type ManagedAttemptOutcomeHandler = (
 	outcome: ManagedAttemptOutcome,
@@ -127,6 +213,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 
 	/** Receives a managed invocation outcome without publishing provisional lifecycle events. */
 	onManagedAttemptOutcome?: ManagedAttemptOutcomeHandler;
+	/** Per-attempt scope allocator for direct loop callers. */
+	attemptMinter?: AttemptMinter;
+	/** Scope allocated by the owning Agent for the first attempt in this loop. */
+	initialScope?: AttemptScope;
 
 	/**
 	 * When to interrupt tool execution for steering messages.
@@ -199,7 +289,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * }
 	 * ```
 	 */
-	transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+	transformContext?: (messages: AgentMessage[], signal?: AbortSignal, scope?: AttemptScope) => Promise<AgentMessage[]>;
 
 	/**
 	 * Resolves an API key dynamically for each LLM call.
@@ -383,6 +473,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	resourceLedger?: RunResourceLedger;
 	/** Stable resource ownership identifier for this prompt run. */
 	resourceRunId?: string;
+	/** Immutable logical cancellation domain bound by the resource ledger. */
+	resourceCancellationDomain?: RunCancellationDomain;
+	/** Agent passes caller ownership; direct loop callers retain loop-owned sealing. */
+	resourceSealOwner?: "caller" | "loop";
+	/** Opaque ownership required to resume a standalone maintenance lifecycle. */
+	standaloneRunOwnership?: StandaloneRunOwnership;
 }
 
 /**
@@ -526,7 +622,8 @@ export interface RenderResultOptions {
  * Apps can extend via declaration merging.
  */
 export interface AgentToolContext {
-	// Empty by default - apps extend via declaration merging
+	/** Per-attempt scope used to attribute tool lifecycle and extension delivery. */
+	attemptScope?: AttemptScope;
 }
 
 export type AgentToolExecFn<TParameters extends TSchema = TSchema, TDetails = any, TTheme = unknown> = (
@@ -597,7 +694,7 @@ export interface AgentContext {
  */
 export type AgentEvent =
 	// Agent lifecycle
-	| { type: "agent_start" }
+	| { type: "agent_start"; scope?: AttemptScope }
 	| {
 			type: "agent_end";
 			messages: AgentMessage[];
@@ -608,16 +705,43 @@ export type AgentEvent =
 			/** Present iff `AgentTelemetryConfig` was supplied on this run. */
 			telemetry?: AgentRunSummary;
 			coverage?: AgentRunCoverage;
+			scope?: AttemptScope;
 	  }
 	// Turn lifecycle - a turn is one assistant response + any tool calls/results
-	| { type: "turn_start" }
-	| { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
+	| { type: "turn_start"; scope?: AttemptScope }
+	| { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[]; scope?: AttemptScope }
 	// Message lifecycle - emitted for user, assistant, and toolResult messages
-	| { type: "message_start"; message: AgentMessage }
+	| { type: "message_start"; message: AgentMessage; scope?: AttemptScope }
 	// Only emitted for assistant messages during streaming
-	| { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
-	| { type: "message_end"; message: AgentMessage }
+	| {
+			type: "message_update";
+			message: AgentMessage;
+			assistantMessageEvent: AssistantMessageEvent;
+			scope?: AttemptScope;
+	  }
+	| { type: "message_end"; message: AgentMessage; scope?: AttemptScope }
 	// Tool execution lifecycle
-	| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any; intent?: string }
-	| { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
-	| { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError?: boolean };
+	| {
+			type: "tool_execution_start";
+			toolCallId: string;
+			toolName: string;
+			args: any;
+			intent?: string;
+			scope?: AttemptScope;
+	  }
+	| {
+			type: "tool_execution_update";
+			toolCallId: string;
+			toolName: string;
+			args: any;
+			partialResult: any;
+			scope?: AttemptScope;
+	  }
+	| {
+			type: "tool_execution_end";
+			toolCallId: string;
+			toolName: string;
+			result: any;
+			isError?: boolean;
+			scope?: AttemptScope;
+	  };