@gajae-code/coding-agent 0.18.5 → 0.18.6

package/src/sdk/host/control/dispatch.ts

@@ -93,6 +93,7 @@ const IDEMPOTENCY_TTL_MS = 15 * 60 * 1_000;
 const MAX_IDEMPOTENCY_ENTRIES = 256;
 
 const sessionChains = new WeakMap<ControlSurface, Promise<void>>();
+const pendingReplacementBarriers = new WeakMap<ControlSurface, Promise<void>>();
 interface IdempotencyEntry {
 	hash: string;
 	expiresAt: number;
@@ -189,6 +190,19 @@ function invalidInput(message: string): never {
 	throw new TypedControlError("invalid_input", message);
 }
 
+const EXPECTED_SDK_RUN_TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}:[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+
+function enqueueReplacementBarrier(surface: ControlSurface): () => void {
+	const previous = pendingReplacementBarriers.get(surface) ?? Promise.resolve();
+	const { promise: current, resolve: resolveCurrent } = Promise.withResolvers<void>();
+	const barrier = previous.then(() => current);
+	pendingReplacementBarriers.set(surface, barrier);
+	return () => {
+		resolveCurrent();
+		if (pendingReplacementBarriers.get(surface) === barrier) pendingReplacementBarriers.delete(surface);
+	};
+}
+
 /**
  * C04 `turn.abort` dispatch.
  *
@@ -244,7 +258,11 @@ function invoke(
 		case "turn.prompt":
 			return surface.prompt(text(input), input.images, input.clientRef as string | undefined);
 		case "turn.steer":
-			return surface.steer(text(input), typeof input.clientRef === "string" ? input.clientRef : undefined);
+			return surface.steer(
+				text(input),
+				typeof input.clientRef === "string" ? input.clientRef : undefined,
+				Object.hasOwn(input, "expectedSdkRunToken") ? (input.expectedSdkRunToken as string) : undefined,
+			);
 		case "turn.follow_up":
 			return surface.followUp(text(input));
 		case "turn.abort":
@@ -486,6 +504,15 @@ export function dispatchControl(
 		);
 	if (!isInput(request.input))
 		return Promise.resolve(failure(request.id, "invalid_input", "Control input must be an object."));
+	if (
+		row.sdkId === "turn.steer" &&
+		Object.hasOwn(request.input, "expectedSdkRunToken") &&
+		(typeof request.input.expectedSdkRunToken !== "string" ||
+			!EXPECTED_SDK_RUN_TOKEN_PATTERN.test(request.input.expectedSdkRunToken))
+	)
+		return Promise.resolve(
+			failure(request.id, "invalid_input", "expectedSdkRunToken must be a commandId:turnId pair."),
+		);
 	if (
 		row.sdkId === "turn.abort" &&
 		((brokerAbortFieldPresent && !brokerAbortAuthorized) ||
@@ -538,10 +565,31 @@ export function dispatchControl(
 	const work = () => execute(surface, row, dispatchRequest);
 	if (row.sdkId === "turn.abort_and_prompt") {
 		const cancellable = surface as PreflightCancellableSurface;
-		if (Object.hasOwn(cancellable, "cancelPendingPreflights")) cancellable.cancelPendingPreflights?.();
-		return serialize(surface, work);
+		const releaseBarrier = enqueueReplacementBarrier(surface);
+		try {
+			if (Object.hasOwn(cancellable, "cancelPendingPreflights")) cancellable.cancelPendingPreflights?.();
+			return serialize(surface, async () => {
+				try {
+					return await work();
+				} finally {
+					releaseBarrier();
+				}
+			});
+		} catch (error) {
+			releaseBarrier();
+			throw error;
+		}
 	}
 	if (row.idempotency === "idempotent" && dispatchRequest.idempotencyKey)
 		return idempotent(surface, row, dispatchRequest, work);
-	return row.idempotency === "ordered" && row.sdkId !== "retry.now" ? serialize(surface, work) : work();
+	if (row.sdkId === "turn.steer") {
+		const replacementBarrier = pendingReplacementBarriers.get(surface);
+		return replacementBarrier ? replacementBarrier.then(work) : work();
+	}
+	// Active feedback must reach the worker even while an earlier ordered control
+	// waits for that worker. Correlated steer admission remains deduplicated by
+	// the runtime reconciliation store, independently of this dispatch chain.
+	return row.idempotency === "ordered" && row.sdkId !== "retry.now" && row.sdkId !== "turn.steer"
+		? serialize(surface, work)
+		: work();
 }

package/src/sdk/host/control/operations.ts

@@ -22,7 +22,7 @@ export type ControlInput = Record<string, unknown>;
  */
 export interface ControlSurface {
 	prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
-	steer(text: string, clientRef?: string): Promise<ControlValue> | ControlValue;
+	steer(text: string, clientRef?: string, expectedSdkRunToken?: string): Promise<ControlValue> | ControlValue;
 	followUp(text: string): Promise<ControlValue> | ControlValue;
 	abort(): Promise<ControlValue> | ControlValue;
 	/** Terminal abort: stop the current root turn (and optionally exact owned work). */

package/src/sdk/host/session-runtime.test.ts

@@ -290,7 +290,7 @@ test("session.last_assistant returns the latest projected readable text past non
 	});
 });
 
-test("session.last_assistant returns resource_gone when the projected transcript has no readable assistant text", async () => {
+test("session.last_assistant returns null when the projected transcript has no readable assistant text", async () => {
 	const sessionId = "last-assistant-empty";
 	const ctx = extensionContext(sessionId, "/tmp", {
 		transcript: [
@@ -311,7 +311,7 @@ test("session.last_assistant returns resource_gone when the projected transcript
 		],
 	});
 
-	expect(await queryLastAssistant(ctx, sessionId)).toMatchObject({ ok: false, error: { code: "resource_gone" } });
+	expect(await queryLastAssistant(ctx, sessionId)).toMatchObject({ ok: true, page: { items: [null] } });
 });
 
 test("native prompt reconciliation fails closed for an explicitly empty assistant result", () => {
@@ -4142,6 +4142,7 @@ describe("SessionSdkSessionRuntime", () => {
 interface PreflightHooks {
 	onPreflightAccepted?: () => void;
 	onPreflightAcceptCommit?: () => void | Promise<void>;
+	expectedSdkRunToken?: string;
 }
 
 interface ResponseFrame {
@@ -4482,6 +4483,43 @@ function neverSettlingPromise(): Promise<void> {
 	return Promise.withResolvers<void>().promise;
 }
 
+test("SDK turn.steer preserves its expected run token and propagates a stale-run rejection", async () => {
+	const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-turn-steer-run-token-"));
+	const staleToken = "ended-command:ended-turn";
+	const clientRef = "stale-steer-ref";
+	const calls: Array<{ content: unknown; deliverAs?: string; expectedSdkRunToken?: string }> = [];
+	let harness: InvocationHarness | undefined;
+	try {
+		harness = await invocationHarness("steer-run-token", cwd, {
+			sendUserMessage: async (content, options) => {
+				calls.push({
+					content,
+					deliverAs: options?.deliverAs,
+					expectedSdkRunToken: options?.expectedSdkRunToken,
+				});
+				if (options?.expectedSdkRunToken === staleToken)
+					throw Object.assign(new Error("The expected SDK run is not active."), { code: "turn_not_active" });
+				return "completed";
+			},
+		});
+
+		const rejected = await harness.control("turn.steer", {
+			text: "stale steer",
+			expectedSdkRunToken: staleToken,
+			clientRef,
+		});
+		expect(rejected).toMatchObject({ ok: false, error: { code: "turn_not_active" } });
+		expect(calls).toEqual([{ content: "stale steer", deliverAs: "steer", expectedSdkRunToken: staleToken }]);
+		expect(await harness.query("turn.steer_status", { clientRef })).toMatchObject({
+			ok: true,
+			result: { status: "rejected" },
+		});
+	} finally {
+		if (harness) await harness.stop();
+		await rm(cwd, { recursive: true, force: true });
+	}
+});
+
 describe("post-acceptance invocation terminalization", () => {
 	test.each([
 		{ status: 402, code: "provider_http_402" },

package/src/sdk/host/session-runtime.ts

@@ -2059,7 +2059,7 @@ function createQuerySurface(
 					: entry.content?.flatMap(block => (block.type === "text" ? [block.text] : [])).join("\n");
 			if (text !== undefined && text.trim().length > 0) return text;
 		}
-		return undefined;
+		return null;
 	};
 	const getProfileCredentialSessionId = () => ctx.credentialSessionId ?? id;
 	const profileSettings = (options.settings ?? ctx.settings) as Pick<Settings, "get"> | undefined;
@@ -2914,6 +2914,7 @@ function createControlSurface(
 	};
 	type InternalSendOptions = NonNullable<Parameters<ExtensionAPI["sendUserMessage"]>[1]> & {
 		sdkRunCapability?: SdkRunCapability;
+		expectedSdkRunToken?: string;
 	};
 	type InternalSdkApi = Omit<ExtensionAPI, "sendUserMessage"> & {
 		sendUserMessage: (
@@ -4243,23 +4244,30 @@ function createControlSurface(
 				),
 			);
 		},
-		steer: async (text, clientRef) => {
+		steer: async (text, clientRef, expectedSdkRunToken) => {
 			const invalid = validateRequiredPromptText("turn.steer", { text });
 			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
 			const retainedClientRef = normalizeClientRef(clientRef);
+			const sendSteer = () =>
+				sendSdkUserMessage(text, {
+					deliverAs: "steer",
+					...(expectedSdkRunToken === undefined ? {} : { expectedSdkRunToken }),
+				});
 			if (retainedClientRef === undefined) {
 				const correlation = newCorrelation();
-				await sendSdkUserMessage(text, { deliverAs: "steer" });
+				await sendSteer();
 				return { accepted: true, ...correlation };
 			}
 			const durable = steerReconciliation;
 			const reservation = await durable.reserveSteer(retainedClientRef, text);
 			if (reservation.replay) return { accepted: reservation.result.status === "accepted", ...reservation.result };
 			try {
-				await sendSdkUserMessage(text, { deliverAs: "steer" });
+				await sendSteer();
 				return { accepted: true, ...(await durable.settleSteer(retainedClientRef, "accepted")) };
 			} catch (error) {
-				return { accepted: false, ...(await durable.settleSteer(retainedClientRef, "rejected", error)) };
+				const settled = await durable.settleSteer(retainedClientRef, "rejected", error);
+				if (expectedSdkRunToken !== undefined) throw error;
+				return { accepted: false, ...settled };
 			}
 		},
 		followUp: async text => {

package/src/sdk/index.ts

@@ -21,6 +21,7 @@ export type {
 	TrackedSendUserMessageOptions,
 } from "../session/agent-session";
 export * as bus from "./bus";
+export * from "./diagnostics/observe-broker";
 export * as host from "./host";
 export * as lifecycle from "./lifecycle";
 export * as mcp from "./mcp";

package/src/sdk/lifecycle-session.ts

@@ -123,6 +123,7 @@ export async function createLifecycleAgentSession(
 			// inside the broker's readiness window is what kills the child at the
 			// cutoff; the host resumes it once readiness is published.
 			deferMemoryBackendStartup: true,
+			deferOptionalModelRefresh: true,
 			[lifecycleStartupCapabilityOption]: capability,
 			...(mcpStartupTimeoutMs !== undefined ? { [lifecycleMcpStartupTimeoutOption]: mcpStartupTimeoutMs } : {}),
 		} as CreateAgentSessionOptions & {

package/src/sdk/protocol/operation-registry.ts

@@ -267,7 +267,7 @@ function controlErrors(id: string): string[] {
 		// refuses a session with no selected model before admission. The code is
 		// appended: ACP machine-only mapping reads errorCodes[0].
 		C01: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed", "model_not_selected"],
-		C02: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
+		C02: ["turn_not_active", "client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C09: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C06: ["action_claimed"],
 		C07: ["action_claimed", "terminal_uncertain"],

package/src/sdk/router/session-router.ts

@@ -287,6 +287,8 @@ export interface SessionRouterOptions {
 	agentDir: string;
 	/** Limits attachment to exact ids selected by a Broker-scoped operation. */
 	sessionIds?: readonly string[];
+	/** Dynamically limits attachment to sessions currently owned by the caller. */
+	attachFilter?: (sessionId: string) => boolean;
 	/** Marks default SDK clients as notification-only observers; demanding by default. */
 	observer?: boolean;
 	deps?: SessionRouterDeps;
@@ -615,6 +617,7 @@ type AdoptedSession = {
 export class SessionRouter {
 	readonly #agentDir: string;
 	readonly #sessionIds: ReadonlySet<string> | undefined;
+	readonly #attachFilter: ((sessionId: string) => boolean) | undefined;
 	readonly #observer: boolean;
 	readonly #deps: SessionRouterDeps;
 	readonly #correlateFrame: SessionRouterFrameCorrelator;
@@ -657,6 +660,7 @@ export class SessionRouter {
 	constructor(options: SessionRouterOptions) {
 		this.#agentDir = options.agentDir;
 		this.#sessionIds = options.sessionIds === undefined ? undefined : new Set(options.sessionIds);
+		this.#attachFilter = options.attachFilter;
 		this.#observer = options.observer === true;
 		this.#deps = options.deps ?? {};
 		this.#correlateFrame = options.correlateFrame ?? fallbackCorrelation;
@@ -797,6 +801,7 @@ export class SessionRouter {
 		if (
 			sessionId !== fallback.sessionId ||
 			(this.#sessionIds !== undefined && !this.#sessionIds.has(sessionId ?? "")) ||
+			(this.#attachFilter !== undefined && !this.#attachFilter(sessionId ?? "")) ||
 			endpointGeneration === undefined ||
 			pid === undefined ||
 			endpointMtimeMs === undefined ||
@@ -1294,7 +1299,8 @@ export class SessionRouter {
 				session.live &&
 				isSessionAuthorityEligible(session) &&
 				!session.terminalUncertain &&
-				(this.#sessionIds === undefined || this.#sessionIds.has(session.sessionId)),
+				(this.#sessionIds === undefined || this.#sessionIds.has(session.sessionId)) &&
+				(this.#attachFilter === undefined || this.#attachFilter(session.sessionId)),
 		);
 		const liveIds = new Set(live.map(session => session.sessionId));
 		const attachedIds = new Set<string>();

package/src/sdk/session.ts

@@ -59,7 +59,11 @@ import { loadCapability, reset as resetCapabilities } from "../capability";
 import { type Rule, ruleCapability, setActiveRules } from "../capability/rule";
 import type { SourceMeta } from "../capability/types";
 import { AUTOROUTING_INACTIVE_WARNING } from "../config/autorouting-contract";
-import { ModelProfileCredentialError, resolveMissingSessionModelRecovery } from "../config/model-profile-activation";
+import {
+	isSessionCredentialPinBlocking,
+	ModelProfileCredentialError,
+	resolveMissingSessionModelRecovery,
+} from "../config/model-profile-activation";
 import { resolveModelProfileName } from "../config/model-profile-contract";
 import { resolveProfileBindings } from "../config/model-profiles";
 import { kNoAuth, ModelRegistry } from "../config/model-registry";
@@ -577,6 +581,12 @@ export interface CreateAgentSessionOptions {
 	 * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
 	 */
 	deferMemoryBackendStartup?: boolean;
+	/**
+	 * Skip optional model-catalog discovery during lifecycle startup. ACP hosts must
+	 * publish their endpoint before unrelated provider credential refreshes begin.
+	 * @internal lifecycle-only startup guard.
+	 */
+	deferOptionalModelRefresh?: boolean;
 
 	/** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
 	enableLsp?: boolean;
@@ -695,6 +705,22 @@ export interface CreateAgentSessionResult {
 	gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
 }
 
+/**
+ * Start optional provider/model discovery only when it is safe to add work to
+ * the caller's startup graph. Lifecycle hosts deliberately skip this during
+ * construction: discovery preflights every configured provider and may refresh
+ * an unrelated OAuth credential while several hosts are opening the same DB.
+ */
+export function startOptionalModelRefresh(
+	modelRegistry: Pick<ModelRegistry, "refreshInBackground">,
+	credentialSessionId: string | undefined,
+	deferred: boolean,
+): boolean {
+	if (deferred) return false;
+	modelRegistry.refreshInBackground("online-if-uncached", credentialSessionId);
+	return true;
+}
+
 export interface DeferredMcpConfigStartupResult {
 	loadedToolCount: number;
 	hasErrors: boolean;
@@ -1970,11 +1996,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				options.preferredCredentialSelector.selector,
 			);
 		}
+		// A runtime key or this registry's literal models.yml apiKey outranks an
+		// unavailable pin; without one the provider stays blocked (never retargeted).
+		const isCredentialPinBlocking = (provider: string): boolean =>
+			isSessionCredentialPinBlocking(modelRegistry, provider, credentialSessionId);
 		const modelApiKeyAvailability = new Map<string, boolean>();
 		const getModelAvailabilityKey = (candidate: Model): string =>
 			`${candidate.provider}\u0000${candidate.baseUrl ?? ""}`;
 		const hasModelApiKey = async (candidate: Model): Promise<boolean> => {
-			if (authStorage.hasSessionCredentialUnavailable(candidate.provider, credentialSessionId)) return false;
+			if (isCredentialPinBlocking(candidate.provider)) return false;
 			const availabilityKey = getModelAvailabilityKey(candidate);
 			const cached = modelApiKeyAvailability.get(availabilityKey);
 			if (cached !== undefined) {
@@ -2000,6 +2030,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const key = await modelRegistry
 				.getApiKey(candidate, credentialSessionId, { credentialSelector })
 				.catch(error => {
+					if (isCredentialPinBlocking(candidate.provider)) return undefined;
 					if (credentialSelector) {
 						logger.debug("Credential selector did not match model availability candidate", {
 							provider: candidate.provider,
@@ -2148,7 +2179,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				settings,
 			);
 			await refreshMissingQualifiedModelProviders(startupModelSelectors, modelRegistry, credentialSessionId);
-			modelRegistry.refreshInBackground("online-if-uncached", credentialSessionId);
+			startOptionalModelRefresh(modelRegistry, credentialSessionId, options.deferOptionalModelRefresh === true);
 		}
 
 		const hasExplicitModel = options.model !== undefined || options.modelPattern !== undefined;
@@ -2241,8 +2272,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					{
 						managedFallback: defaultModelEntries.length > 1,
 						canonicalSessionId: providerSessionId,
-						isCredentialUnavailable: provider =>
-							authStorage.hasSessionCredentialUnavailable(provider, credentialSessionId),
+						isCredentialUnavailable: isCredentialPinBlocking,
 						...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
 					},
 				);
@@ -2297,7 +2327,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			!hasExplicitModel &&
 			!model &&
 			defaultRoleSpec.model &&
-			!authStorage.hasSessionCredentialUnavailable(defaultRoleSpec.model.provider, credentialSessionId) &&
+			!isCredentialPinBlocking(defaultRoleSpec.model.provider) &&
 			(!preferredCredentialProvider || defaultRoleSpec.model.provider === preferredCredentialProvider)
 		) {
 			const settingsDefaultModel = defaultRoleSpec.model;
@@ -4236,8 +4266,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				{
 					managedFallback: defaultModelEntries.length > 1,
 					canonicalSessionId: providerSessionId,
-					isCredentialUnavailable: provider =>
-						authStorage.hasSessionCredentialUnavailable(provider, credentialSessionId),
+					isCredentialUnavailable: isCredentialPinBlocking,
 					...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
 				},
 			);