@gajae-code/coding-agent 0.15.4 → 0.15.6

package/src/session/fold-coordinator.ts

@@ -0,0 +1,433 @@
+/**
+ * Session-owned fold/wake coordinator.
+ *
+ * Folding a running foreground wait is a lifecycle handoff across three
+ * independently scheduled domains — the tool observer, the job owner, and
+ * agent-turn admission — so it needs ONE linearization point. That is this
+ * coordinator: a synchronous prologue claims the fold and arms the steering
+ * fence with no `await` in between, and only then does an async tail capture and
+ * persist the receipt.
+ *
+ * Two invariants are load-bearing and easy to get wrong:
+ *
+ * 1. **Identity is the `AsyncJob` instance, acquired once.** Job ids and
+ *    generations are manager-local, so two managers can mint the same
+ *    `bg_1`/`job:1` pair. Slots are therefore keyed by the object itself,
+ *    obtained exactly once through the registration-bound
+ *    {@link FoldAdapter.getJob} and retained for the rest of the transaction.
+ *    Nothing in the fold path may consult an ambient, singleton, or
+ *    endpoint-resolved manager.
+ * 2. **A delivery callback can run more than once.** The async job manager
+ *    re-pushes the SAME delivery object on retry, so the receipt is attached to
+ *    a carrier keyed by that object BEFORE the slot is released. A retried
+ *    delivery therefore still carries its receipt and can never silently
+ *    degrade into an ordinary receipt-less completion.
+ */
+import type { AsyncJob } from "../async/job-manager";
+import foldReceiptPrompt from "../prompts/tools/fold-receipt.md" with { type: "text" };
+
+/**
+ * Idle-flush merge window.
+ *
+ * Completions that land within this window coalesce into ONE wake turn. The
+ * previous 1ms debounce meant staggered completions each bought their own full
+ * LLM turn. Deliberately a fixed internal constant, not a setting: the contract
+ * is one merge window, and a per-user knob would let wake behavior differ
+ * between sessions.
+ */
+export const FOLD_WAKE_MERGE_WINDOW_MS = 800;
+
+/** The wait kinds that can be folded. `task`/`subagent` awaits are a non-goal. */
+export type FoldWaitKind = "bash-managed" | "client-terminal" | "bash-pty";
+
+/** Outcome of settling the foreground caller. Exactly one party may settle it. */
+export type ForegroundSettleOutcome = "resolved" | "already-settled";
+
+/**
+ * How a folded job's output is retrieved later. Deliberately a structured
+ * handle over already-implemented paths rather than an invented URI scheme:
+ * there is no `job://` resolver, and inventing one would make the reference
+ * unresolvable in exactly the degraded case it exists for.
+ */
+export interface JobOutputRetrieval {
+	jobId: string;
+	generation: string;
+	/** Human/model-facing retrieval instruction naming a real mechanism. */
+	instruction: string;
+}
+
+/** Durable record captured at fold time and replayed into the wake turn. */
+export interface FoldReceipt {
+	jobId: string;
+	jobGeneration: string;
+	kind: FoldWaitKind;
+	label: string;
+	outputRef: JobOutputRetrieval;
+	/** What the interrupted turn still intended to do, so the wake can finish it. */
+	remainingIntent: string | undefined;
+	foldedAt: number;
+	/** Only command kinds can change directory; task-style waits never do. */
+	cwdSensitive: boolean;
+}
+
+/** A terminal completion observed for a folded job. */
+export interface ForegroundTerminalPayload {
+	jobId: string;
+	generation: string;
+	text: string;
+}
+
+/**
+ * Per-wait fold capability. `getJob` is bound at registration over the manager
+ * that registered THIS job, which is what makes cross-manager identity safe.
+ */
+export interface FoldAdapter {
+	readonly kind: FoldWaitKind;
+	readonly jobId: string;
+	readonly jobGeneration: string;
+	readonly label: string;
+	readonly cwdSensitive: boolean;
+	/** Signal for the foreground wait; aborting capture must roll back the fold. */
+	readonly signal?: AbortSignal;
+	/** True only when the adapter was created by a model-owned Agent turn. */
+	readonly originatingTurn?: boolean;
+	readonly outputRef: JobOutputRetrieval;
+	/** Registration-bound resolver: the job for this adapter, or undefined once evicted or reused. */
+	readonly getJob: () => AsyncJob | undefined;
+	/** Settle the foreground caller with the fold result. Idempotent. */
+	readonly detachObserver: (receipt: FoldReceipt) => ForegroundSettleOutcome;
+	/** Hand a parked completion back to a still-attached observer. Idempotent. */
+	readonly resolveForegroundObserver: (payload: ForegroundTerminalPayload) => ForegroundSettleOutcome;
+}
+
+export type FoldRequestResult =
+	| { status: "folded"; receipt: FoldReceipt }
+	| { status: "unavailable"; reason: string }
+	| { status: "already-terminal"; reason: string }
+	| { status: "capture-failed"; reason: string };
+
+/** What a delivery should carry, decided by the durable slot state (T2). */
+export type FoldDeliveryDisposition =
+	| { kind: "ordinary" }
+	| { kind: "parked" }
+	| { kind: "receipt"; receipt: FoldReceipt; text: string };
+
+interface ReservedSlot {
+	state: "reserved";
+	adapter: FoldAdapter;
+	parked: ForegroundTerminalPayload | undefined;
+	parkedAt: number | undefined;
+}
+
+interface PresentSlot {
+	state: "present";
+	adapter: FoldAdapter;
+	receipt: FoldReceipt;
+}
+
+type FoldSlot = ReservedSlot | PresentSlot;
+
+export interface FoldCoordinatorDeps {
+	/**
+	 * Fence old-turn steering admission and return the release handle. Armed
+	 * synchronously inside the prologue because the agent loop polls steering
+	 * upstream of its pause checkpoint; fencing there keeps queued steering
+	 * intact instead of draining it.
+	 */
+	armSteeringFence: () => () => void;
+	/** Whether this fold belongs to a currently running Agent turn. */
+	hasActiveTurn?: () => boolean;
+	/** Arm the cooperative stop so the turn ends after the fold result, never via abort. */
+	requestStop: () => void;
+	/** Capture what the interrupted turn still intended to accomplish. */
+	captureRemainingIntent: () => Promise<string | undefined> | string | undefined;
+	/**
+	 * Push a parked completion into the wake path. The delivery seam parks a
+	 * completion that arrives before the receipt exists; when the fold later
+	 * replays it (A6), THIS is what makes the wake happen rather than relying on
+	 * an unrelated idle rearm to rescue it.
+	 */
+	deliverParked: (job: AsyncJob, disposition: { kind: "receipt"; receipt: FoldReceipt; text: string }) => void;
+}
+
+/** Why a slot is being retired, which decides whether retiring is safe. */
+export type FoldRetireReason = "cancel" | "evict";
+
+/**
+ * Render a fold receipt for the wake turn.
+ *
+ * Carries the job id, a real retrieval handle, and the captured remaining
+ * intent, so the wake turn can finish the ORIGINAL task instead of only
+ * reporting that a command ended. The cwd caveat is included only for wait
+ * kinds that can actually change directory.
+ */
+export function describeFoldReceipt(receipt: FoldReceipt): string {
+	const cwdNotice = receipt.cwdSensitive
+		? "Session cwd is unchanged; any directory change made by the folded command does not apply to later commands.\n"
+		: "";
+	const intentNotice = receipt.remainingIntent
+		? `Complete the original request, which was: ${receipt.remainingIntent}`
+		: "";
+	return foldReceiptPrompt
+		.replace("{{kind}}", () => receipt.kind)
+		.replace("{{jobId}}", () => receipt.jobId)
+		.replace("{{outputInstruction}}", () => receipt.outputRef.instruction)
+		.replace("{{cwdNotice}}", () => cwdNotice)
+		.replace("{{intentNotice}}", () => intentNotice)
+		.trim();
+}
+
+export class FoldCoordinator {
+	/**
+	 * Slots and receipt carriers are keyed by the `AsyncJob` INSTANCE, so two
+	 * managers minting identical ids/generations can never collide, and an entry
+	 * cannot outlive the object it belongs to.
+	 */
+	readonly #slots = new WeakMap<AsyncJob, FoldSlot>();
+	readonly #carriers = new WeakMap<AsyncJob, FoldReceipt>();
+	readonly #participants = new Map<number, FoldAdapter>();
+	#nextParticipantId = 0;
+	readonly #folding = new WeakSet<AsyncJob>();
+	/** Jobs whose completion notice has already been emitted. */
+	readonly #noticed = new WeakSet<AsyncJob>();
+	/** Jobs whose receipt-bearing completion has already been queued. */
+	readonly #delivered = new WeakSet<AsyncJob>();
+	readonly #deps: FoldCoordinatorDeps;
+
+	constructor(deps: FoldCoordinatorDeps) {
+		this.#deps = deps;
+	}
+
+	/** Register a foldable wait. The most recently registered wait is the default target. */
+	registerParticipant(adapter: FoldAdapter): () => void {
+		const key = ++this.#nextParticipantId;
+		this.#participants.set(key, adapter);
+		return () => {
+			if (this.#participants.get(key) === adapter) this.#participants.delete(key);
+		};
+	}
+
+	/** Whether any wait is currently foldable, for the key-availability gate. */
+	hasFoldableParticipant(): boolean {
+		return this.#participants.size > 0;
+	}
+
+	/** Deterministic target: newest registration wins, so the chord folds what the user is watching. */
+	resolveTarget(): FoldAdapter | undefined {
+		let target: FoldAdapter | undefined;
+		for (const adapter of this.#participants.values()) target = adapter;
+		return target;
+	}
+
+	/**
+	 * T1. Synchronous prologue then async durability tail.
+	 *
+	 * Nothing awaits before the slot is reserved and the fence is armed, so a
+	 * completion or a steering submission that races the capture cannot slip
+	 * past into the old turn.
+	 */
+	async requestFold(explicit?: FoldAdapter): Promise<FoldRequestResult> {
+		// S1 resolve target.
+		const adapter = explicit ?? this.resolveTarget();
+		if (!adapter) return { status: "unavailable", reason: "no foldable wait is registered" };
+
+		// S2 acquire identity ONCE through the registration-bound resolver.
+		const job = adapter.getJob();
+		if (!job) return { status: "already-terminal", reason: "the wait already settled or was evicted" };
+		if (job.generation !== adapter.jobGeneration) {
+			return { status: "already-terminal", reason: "the job id was reused under a new generation" };
+		}
+		if (this.#folding.has(job) || this.#slots.has(job)) {
+			return { status: "unavailable", reason: "a fold is already in progress for this wait" };
+		}
+
+		// S3 claim + reserve, S4 hand-off is the reservation itself, S5 arm the fence.
+		this.#folding.add(job);
+		this.#slots.set(job, { state: "reserved", adapter, parked: undefined, parkedAt: undefined });
+		const fencesOriginatingTurn = adapter.originatingTurn ?? this.#deps.hasActiveTurn?.() ?? true;
+		const releaseFence = fencesOriginatingTurn ? this.#deps.armSteeringFence() : () => {};
+
+		let remainingIntent: string | undefined;
+		try {
+			// A1 capture.
+			const signal = adapter.signal;
+			if (signal?.aborted) throw new Error("fold capture aborted");
+			const capture = Promise.resolve(this.#deps.captureRemainingIntent());
+			if (!fencesOriginatingTurn) {
+				remainingIntent = undefined;
+			} else if (!signal) {
+				remainingIntent = await capture;
+			} else {
+				const aborted = Promise.withResolvers<never>();
+				const onAbort = () => aborted.reject(new Error("fold capture aborted"));
+				signal.addEventListener("abort", onAbort, { once: true });
+				try {
+					remainingIntent = await Promise.race([capture, aborted.promise]);
+				} finally {
+					signal.removeEventListener("abort", onAbort);
+				}
+			}
+		} catch (error) {
+			return this.#rollback(job, adapter, releaseFence, error instanceof Error ? error.message : String(error));
+		}
+
+		// T-R3a: revalidate the reservation after the await. A cancellation during
+		// capture already retired the slot; it must NOT be recreated here, and the
+		// participant must not be left advertised as folding.
+		const current = this.#slots.get(job);
+		if (!current || current.adapter !== adapter) {
+			this.#folding.delete(job);
+			releaseFence();
+			return { status: "already-terminal", reason: "the wait settled while its receipt was being captured" };
+		}
+		if (adapter.signal?.aborted || job.status !== "running") {
+			return this.#rollback(job, adapter, releaseFence, "the wait settled while its receipt was being captured");
+		}
+
+		const receipt: FoldReceipt = {
+			jobId: adapter.jobId,
+			jobGeneration: adapter.jobGeneration,
+			kind: adapter.kind,
+			label: adapter.label,
+			outputRef: adapter.outputRef,
+			remainingIntent,
+			foldedAt: Date.now(),
+			cwdSensitive: adapter.cwdSensitive,
+		};
+
+		// A2 promote to present, preserving any payload parked during capture.
+		const parked = current.state === "reserved" ? current.parked : undefined;
+		this.#slots.set(job, { state: "present", adapter, receipt });
+
+		// A3 detach the observer, A4 arm the cooperative stop, A5 leave folding.
+		const detached = adapter.detachObserver(receipt);
+		if (detached === "already-settled") {
+			this.#slots.delete(job);
+			this.#folding.delete(job);
+			releaseFence();
+			return { status: "already-terminal", reason: "the foreground observer already settled" };
+		}
+		if (fencesOriginatingTurn) this.#deps.requestStop();
+		this.#folding.delete(job);
+
+		// A6 flush: replay a parked completion through the same T2 branch so it
+		// takes the receipt exactly once instead of being handled specially — and
+		// push it into the wake path, because the delivery seam already returned
+		// early on it and will not retry.
+		if (parked) {
+			const replayed = this.onDelivery(job, parked.text);
+			if (replayed.kind === "receipt") this.#deps.deliverParked(job, replayed);
+		}
+
+		// A7 the fence stays armed until the turn actually stops; releasing here
+		// would readmit old-turn steering into the run being wound down.
+		return { status: "folded", receipt };
+	}
+
+	/**
+	 * T2. Decide what a delivery carries, branching on the DURABLE slot state
+	 * rather than on transient hand-off state.
+	 *
+	 * `present` attaches the receipt to the retry-stable carrier BEFORE clearing
+	 * the slot, so a retried invocation still finds it.
+	 */
+	onDelivery(job: AsyncJob, text: string): FoldDeliveryDisposition {
+		const carried = this.#carriers.get(job);
+		if (carried) return { kind: "receipt", receipt: carried, text };
+
+		const slot = this.#slots.get(job);
+		if (!slot) return { kind: "ordinary" };
+
+		if (slot.state === "reserved") {
+			// Park: the receipt does not exist yet, so enqueue nothing. A6 replays it.
+			slot.parked = { jobId: slot.adapter.jobId, generation: slot.adapter.jobGeneration, text };
+			slot.parkedAt = Date.now();
+			const timer = setTimeout(() => this.retire(job, "evict"), FOLD_WAKE_MERGE_WINDOW_MS * 4);
+			timer.unref();
+			return { kind: "parked" };
+		}
+
+		// Attach first, then release the slot: order matters for retries.
+		this.#carriers.set(job, slot.receipt);
+		this.#slots.delete(job);
+		return { kind: "receipt", receipt: slot.receipt, text };
+	}
+
+	/**
+	 * Retirement. T-R2: never drop a slot that holds an undelivered payload or
+	 * that a still-possible delivery could consume.
+	 *
+	 * - `cancel` retires freely, because a cancelled job enqueues no delivery at
+	 *   all, so no later consumer can arrive.
+	 * - `evict` only retires when the job can no longer deliver. An evicted
+	 *   record still delivers with its retained job object, so a completed or
+	 *   failed job keeps its slot.
+	 */
+	retire(job: AsyncJob, reason: FoldRetireReason): boolean {
+		const slot = this.#slots.get(job);
+		if (!slot) return false;
+
+		if (reason === "cancel") {
+			this.#slots.delete(job);
+			this.#folding.delete(job);
+			return true;
+		}
+
+		if (slot.state === "reserved" && slot.parked !== undefined) {
+			const parkedAt = slot.parkedAt ?? Date.now();
+			if (Date.now() - parkedAt < FOLD_WAKE_MERGE_WINDOW_MS * 4) return false;
+			const parked = slot.parked;
+			this.#slots.delete(job);
+			this.#folding.delete(job);
+			slot.adapter.resolveForegroundObserver(parked);
+			return true;
+		}
+		if (job.status === "cancelled" || job.status === "paused") {
+			this.#slots.delete(job);
+			this.#folding.delete(job);
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Claim the single completion notice for a job.
+	 *
+	 * Returns true exactly once per job. A delivery can be retried with the same
+	 * object, so an unguarded notice would repeat for one completion.
+	 */
+	claimCompletionNotice(job: AsyncJob): boolean {
+		if (this.#noticed.has(job)) return false;
+		this.#noticed.add(job);
+		return true;
+	}
+
+	/** Claim the receipt-bearing queue entry once across manager delivery retries. */
+	claimCompletionDelivery(job: AsyncJob): boolean {
+		if (this.#delivered.has(job)) return false;
+		this.#delivered.add(job);
+		return true;
+	}
+
+	/** Test/diagnostic view of the durable slot state for a job. */
+	slotStateFor(job: AsyncJob): "none" | "reserved-empty" | "reserved-parked" | "present" | "carried" {
+		const slot = this.#slots.get(job);
+		if (slot?.state === "present") return "present";
+		if (slot?.state === "reserved") return slot.parked === undefined ? "reserved-empty" : "reserved-parked";
+		return this.#carriers.has(job) ? "carried" : "none";
+	}
+
+	#rollback(job: AsyncJob, adapter: FoldAdapter, releaseFence: () => void, reason: string): FoldRequestResult {
+		const slot = this.#slots.get(job);
+		// R1/R2 return the claim and drop the reservation, R3 release the fence so
+		// the preserved steering becomes admissible again, R5 never arm the stop.
+		this.#slots.delete(job);
+		this.#folding.delete(job);
+		releaseFence();
+		// R4 hand a parked completion back to the STILL-ATTACHED observer, which
+		// owns its own acknowledgement path. The coordinator enqueues nothing, so
+		// it cannot race that observer.
+		if (slot?.state === "reserved" && slot.parked) adapter.resolveForegroundObserver(slot.parked);
+		return { status: "capture-failed", reason };
+	}
+}

package/src/session/internal/managed-session-storage.ts

@@ -242,9 +242,8 @@ export interface ManagedFileSnapshot {
 	};
 }
 /**
- * Descriptor identity of one managed file object. Deliberately excludes the
- * content sha256: append receipts must bind the post-operation object without
- * re-reading the whole payload.
+ * Descriptor identity of one managed file object. Append receipts include a
+ * content digest when the append implementation has already computed it.
  */
 export interface ManagedFileIdentity {
 	dev: bigint;
@@ -253,6 +252,7 @@ export interface ManagedFileIdentity {
 	size: number;
 	mtimeNs: bigint;
 	ctimeNs: bigint;
+	sha256?: string;
 }
 
 /**
@@ -281,6 +281,7 @@ function sameManagedIdentity(left: ManagedFileIdentity, right: ManagedFileIdenti
 export interface ManagedBoundedAppendExpectation {
 	readonly dev: string;
 	readonly ino: string;
+	readonly nlink: string;
 	readonly size: string;
 	readonly mtimeNs: string;
 	readonly ctimeNs: string;
@@ -295,6 +296,7 @@ function managedFileIdentityFromNative(identity: RecoveryFsIdentity): ManagedFil
 		size: Number(identity.size),
 		mtimeNs: BigInt(identity.mtimeNs),
 		ctimeNs: BigInt(identity.ctimeNs),
+		...(identity.sha256 ? { sha256: identity.sha256 } : {}),
 	};
 }
 
@@ -1704,6 +1706,7 @@ export class ManagedSessionDescendantStore {
 		return {
 			dev: identity.dev.toString(),
 			ino: identity.ino.toString(),
+			nlink: identity.nlink.toString(),
 			size: identity.size.toString(),
 			mtimeNs: identity.mtimeNs.toString(),
 			ctimeNs: identity.ctimeNs.toString(),
@@ -1718,17 +1721,20 @@ export class ManagedSessionDescendantStore {
 	): ManagedAppendReceipt {
 		this.#beforeMutation();
 		this.#assertBound();
+		let appendExpectation = expected;
 		if (!this.#authority) {
 			const current = captureManagedFileIdentityStreamingNoFollow(this.#resolve(relativePath));
-			if (
-				current.dev.toString() !== expected.dev ||
-				current.ino.toString() !== expected.ino ||
-				current.size.toString() !== expected.size ||
-				current.mtimeNs.toString() !== expected.mtimeNs ||
-				current.ctimeNs.toString() !== expected.ctimeNs ||
-				current.sha256 !== expected.sha256
-			)
+			const identityMatches =
+				current.dev.toString() === expected.dev &&
+				current.ino.toString() === expected.ino &&
+				current.nlink.toString() === expected.nlink &&
+				current.size.toString() === expected.size &&
+				current.sha256 === expected.sha256;
+			if (!identityMatches) {
 				throw new Error("managed_append_identity_mismatch");
+			}
+			// mtime/ctime drift on the same file object is harmless. The append
+			// helper performs its own descriptor-bound mutation check.
 			const appended = appendManagedFileStreamingSync(
 				this.#resolve(relativePath),
 				bytes,
@@ -1738,16 +1744,35 @@ export class ManagedSessionDescendantStore {
 			this.#assertBound();
 			return managedAppendReceiptFromIdentity(appended);
 		}
+		const current = this.captureBoundedAppendExpectation(relativePath);
+		if (!current) throw new Error("managed_append_identity_mismatch");
+		if (
+			current.dev !== expected.dev ||
+			current.ino !== expected.ino ||
+			current.nlink !== expected.nlink ||
+			current.size !== expected.size ||
+			current.sha256 !== expected.sha256
+		)
+			throw new Error("managed_append_identity_mismatch");
+		const descriptorMatches =
+			current.dev === expected.dev &&
+			current.ino === expected.ino &&
+			current.nlink === expected.nlink &&
+			current.size === expected.size &&
+			current.mtimeNs === expected.mtimeNs &&
+			current.ctimeNs === expected.ctimeNs &&
+			current.sha256 === expected.sha256;
+		if (!descriptorMatches) appendExpectation = current;
 		const relative = this.#relative(this.#resolve(relativePath));
 		const appended = this.#authority.appendManaged(
 			relative,
 			bytes,
-			expected.dev,
-			expected.ino,
-			expected.size,
-			expected.mtimeNs,
-			expected.ctimeNs,
-			expected.sha256,
+			appendExpectation.dev,
+			appendExpectation.ino,
+			appendExpectation.size,
+			appendExpectation.mtimeNs,
+			appendExpectation.ctimeNs,
+			appendExpectation.sha256,
 		);
 		if (!appended.ok) throw managedAppendFailure(appended.code);
 		if (!appended.identity)
@@ -1762,15 +1787,28 @@ export class ManagedSessionDescendantStore {
 		expected: ManagedFileIdentity,
 	): ManagedAppendReceipt {
 		const bounded = this.captureBoundedAppendExpectation(relativePath);
-		if (
-			!bounded ||
-			bounded.dev !== expected.dev.toString() ||
-			bounded.ino !== expected.ino.toString() ||
-			bounded.size !== String(expected.size) ||
-			bounded.mtimeNs !== expected.mtimeNs.toString() ||
-			bounded.ctimeNs !== expected.ctimeNs.toString()
-		)
-			throw new Error("managed_append_identity_mismatch");
+		if (!bounded) throw new Error("managed_append_identity_mismatch");
+		const descriptorMatches =
+			bounded.dev === expected.dev.toString() &&
+			bounded.ino === expected.ino.toString() &&
+			bounded.nlink === expected.nlink.toString() &&
+			bounded.size === String(expected.size) &&
+			bounded.mtimeNs === expected.mtimeNs.toString() &&
+			bounded.ctimeNs === expected.ctimeNs.toString();
+		if (!descriptorMatches) {
+			// Metadata-only drift is safe only when the same unlinked file object and
+			// byte-exact predecessor are independently proven. Never accept a changed
+			// object, length, link count, or digest as a benign touch.
+			if (
+				!expected.sha256 ||
+				bounded.dev !== expected.dev.toString() ||
+				bounded.ino !== expected.ino.toString() ||
+				bounded.nlink !== expected.nlink.toString() ||
+				bounded.size !== String(expected.size) ||
+				bounded.sha256 !== expected.sha256
+			)
+				throw new Error("managed_append_identity_mismatch");
+		}
 		return this.appendExpectedSync(relativePath, bytes, bounded);
 	}
 

package/src/session/sdk-run-capability-internal.ts

@@ -0,0 +1,15 @@
+const sdkRunTokenBrand: unique symbol = Symbol("sdkRunToken");
+
+export interface SdkRunCapability {
+	readonly [sdkRunTokenBrand]: string;
+}
+
+export function createSdkRunCapability(token: string): SdkRunCapability {
+	return { [sdkRunTokenBrand]: token };
+}
+
+export function readSdkRunCapability(value: unknown): string | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const token = (value as Partial<SdkRunCapability>)[sdkRunTokenBrand];
+	return typeof token === "string" && token.length > 0 ? token : undefined;
+}

package/src/session/sdk-run-capability.ts

@@ -0,0 +1,2 @@
+export type { SdkRunCapability } from "./sdk-run-capability-internal";
+export { readSdkRunCapability } from "./sdk-run-capability-internal";