@gajae-code/coding-agent 0.12.11 → 0.12.12

package/src/sdk/host/host.ts

@@ -4,6 +4,42 @@ import type { BrokerIndexWriter, HostEndpointAdapters, SdkFrame } from "./types"
 
 export type SdkRequestObserver = (kind: "control" | "query", connectionId: string, frame: SdkFrame) => void;
 
+/**
+ * When a session publishes its replayable readiness signal.
+ *
+ * `immediate` is the stock contract: `start()` publishes `session_ready` at
+ * once, so a chat daemon that attaches (or replays late) surfaces the session
+ * and creates its stock root. `deferred` prepares the session instead: the
+ * session id, endpoint, and broker registration become discoverable authority,
+ * but no readiness exists for any consumer to act on until `activate()` runs.
+ * That ordering is what lets an operator adopt an existing chat root before the
+ * daemon would otherwise have published one of its own.
+ */
+export type SessionReadinessMode = "immediate" | "deferred";
+
+/**
+ * Replayable signal that a deferred session is fully initialized and holding
+ * endpoint authority while its readiness stays withheld.
+ *
+ * It is deliberately not `session_ready`: a broker lifecycle wait can
+ * authenticate it as the child's semantic completion receipt, while every
+ * readiness consumer — chat daemons above all — keeps ignoring it and publishes
+ * no root until the session is explicitly activated.
+ */
+export const SESSION_PREPARED_EVENT = "session_prepared";
+
+/** Every terminal answer an activation attempt can produce. */
+export type SessionActivationOutcome =
+	| "activated"
+	| "already"
+	| "not_prepared"
+	| "generation_changed"
+	| "not_authorized"
+	| "authority_unavailable";
+
+/** Proves that a prepared session may publish readiness at this exact generation. */
+export type SessionActivationGate = (input: { sessionId: string; generation: number }) => boolean | Promise<boolean>;
+
 export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	control?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
 	query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
@@ -23,12 +59,32 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
 	/** Best-effort capabilities mirrored from the native transport for out-of-band consumers. */
 	connectionCapabilities?: (connectionId: string) => ReadonlySet<string> | undefined;
+	/** Readiness publication mode; defaults to the stock immediate contract. */
+	readiness?: SessionReadinessMode;
+	/**
+	 * Authorization for a deferred activation. It is consulted on every attempt
+	 * that would publish readiness and never on an idempotent replay, and a gate
+	 * that fails is never read as authorization.
+	 */
+	activationGate?: SessionActivationGate;
 }
 
 const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
 const CAP_GATED_FRAME_KINDS = new Set(["tool_activity", "reasoning_summary"]);
 const EMPTY_CAPABILITIES: ReadonlySet<string> = new Set();
 
+/** Safe, identifier-free explanations for every refused activation status. */
+const ACTIVATION_MESSAGES: Record<
+	Exclude<SessionActivationOutcome, "activated" | "already"> | "session_mismatch",
+	string
+> = {
+	not_prepared: "The session is not prepared for activation.",
+	generation_changed: "The session endpoint generation changed before activation.",
+	not_authorized: "Session activation is not authorized at this endpoint generation.",
+	authority_unavailable: "Session activation authority could not be read.",
+	session_mismatch: "The activation request addresses a different session.",
+};
+
 /** SDK hosting is independent of notification configuration. Only root sessions host an endpoint. */
 export function shouldHostSdk(_settings: unknown, isTopLevel: boolean, env: NodeJS.ProcessEnv = process.env): boolean {
 	return isTopLevel && env.GJC_SDK_DISABLE !== "1";
@@ -117,9 +173,14 @@ export class SessionSdkHost {
 	readonly reverse: ReverseLeaseRuntime;
 	readonly #options: SessionSdkHostOptions;
 	#started = false;
+	#stopping = false;
 	#stopPromise?: Promise<"stopped">;
 	#unsubscribe?: () => void;
 	#registration?: { writer: BrokerIndexWriter; generation: number };
+	/** The generation whose readiness signal has already been published. */
+	#readyGeneration?: number;
+	/** Serializes activation attempts so a concurrent pair cannot both publish. */
+	#activation: Promise<SessionActivationOutcome> = Promise.resolve("not_prepared");
 
 	constructor(options: SessionSdkHostOptions) {
 		this.#options = options;
@@ -137,6 +198,14 @@ export class SessionSdkHost {
 	get generation(): number {
 		return this.events.generation;
 	}
+	/** True while the session holds endpoint authority but has published no readiness. */
+	get prepared(): boolean {
+		return this.#started && this.#readyGeneration !== this.events.generation;
+	}
+	/** True once readiness for the current generation has been published. */
+	get ready(): boolean {
+		return this.#started && this.#readyGeneration === this.events.generation;
+	}
 	/** Current installed definitions for a live provider capability. */
 	getProviderDefinitions(capability: string): unknown | undefined {
 		return this.reverse.getInstalledDefinitions(capability);
@@ -154,7 +223,13 @@ export class SessionSdkHost {
 	async start(): Promise<"started" | "already"> {
 		if (this.#started) return "already";
 		this.events.restart();
-		this.emitEvent({ name: "session_ready", sessionId: this.#options.sessionId, generation: this.events.generation });
+		if (this.#options.readiness !== "deferred") this.#publishReadiness();
+		else
+			this.emitEvent({
+				name: SESSION_PREPARED_EVENT,
+				sessionId: this.#options.sessionId,
+				generation: this.events.generation,
+			});
 		const disposer = this.#options.onFrame((connectionId, frame) => {
 			void this.#onFrame(connectionId, frame);
 		});
@@ -169,6 +244,61 @@ export class SessionSdkHost {
 		return "started";
 	}
 
+	#publishReadiness(): void {
+		this.emitEvent({ name: "session_ready", sessionId: this.#options.sessionId, generation: this.events.generation });
+		this.#readyGeneration = this.events.generation;
+	}
+
+	/**
+	 * Publish the readiness signal a prepared session withheld.
+	 *
+	 * The attempt is refused unless the session is still started at exactly
+	 * `expectedGeneration` (when supplied) and the activation gate authorizes it
+	 * at that same generation. Authority is re-proved after the gate resolves,
+	 * because a stop or an endpoint roll can land while it is in flight, and an
+	 * exact retry after a successful activation is answered `already` instead of
+	 * publishing a second readiness signal.
+	 */
+	activate(expectedGeneration?: number): Promise<SessionActivationOutcome> {
+		const attempt = this.#activation.then(
+			() => this.#activateOnce(expectedGeneration),
+			() => this.#activateOnce(expectedGeneration),
+		);
+		this.#activation = attempt.then(
+			outcome => outcome,
+			() => "authority_unavailable" as const,
+		);
+		return attempt;
+	}
+
+	async #activateOnce(expectedGeneration?: number): Promise<SessionActivationOutcome> {
+		if (!this.#started) return "not_prepared";
+		const generation = this.events.generation;
+		if (expectedGeneration !== undefined && expectedGeneration !== generation) return "generation_changed";
+		if (this.#readyGeneration === generation) return "already";
+		const gate = this.#options.activationGate;
+		if (gate) {
+			let authorized: boolean;
+			try {
+				authorized = await gate({ sessionId: this.#options.sessionId, generation });
+			} catch {
+				// An unreadable authority is never an authorization.
+				return "authority_unavailable";
+			}
+			if (!authorized) return "not_authorized";
+			// The gate is asynchronous, so the session may have stopped or rolled
+			// while it ran; nothing published below may rest on the earlier proof.
+			// `#started` stays true across the unregister await inside stop(), so an
+			// activation gate that resolves during shutdown would otherwise pass this
+			// re-check and publish readiness after teardown began.
+			if (!this.#started || this.#stopping) return "not_prepared";
+			if (this.events.generation !== generation) return "generation_changed";
+			if (this.#readyGeneration === generation) return "already";
+		}
+		this.#publishReadiness();
+		return "activated";
+	}
+
 	async stop(): Promise<"stopped" | "already"> {
 		if (this.#stopPromise) return this.#stopPromise;
 		if (!this.#started) return "already";
@@ -182,6 +312,9 @@ export class SessionSdkHost {
 	}
 
 	async #stopStartedHost(): Promise<"stopped"> {
+		// Fence before the first await: everything after this point is teardown,
+		// and no in-flight activation may publish readiness across it.
+		this.#stopping = true;
 		this.#unsubscribe?.();
 		this.#unsubscribe = undefined;
 		if (this.#registration?.writer.unregister)
@@ -191,6 +324,7 @@ export class SessionSdkHost {
 				endpointGeneration: this.events.generation,
 			});
 		this.#started = false;
+		this.#stopping = false;
 		return "stopped";
 	}
 
@@ -226,6 +360,22 @@ export class SessionSdkHost {
 			switch (frame.type) {
 				case "control_request": {
 					this.#observeRequest("control", connectionId, frame);
+					// Deferred readiness withholds `session_ready`, but the control
+					// dispatcher was still reachable, so the pre-activation interval made
+					// activation optional for input admission. `session_activate` is a
+					// separate frame type and is unaffected by this gate.
+					if (this.prepared) {
+						await this.#send(connectionId, {
+							type: "control_response",
+							id: requiredString(frame, "id"),
+							ok: false,
+							error: {
+								code: "not_activated",
+								message: "The session is prepared and must be activated before it accepts controls.",
+							},
+						});
+						break;
+					}
 					const result = await this.#options.control?.(connectionId, frame);
 					if (result !== undefined) {
 						const response = { type: "control_response", ...(result as SdkFrame) };
@@ -241,6 +391,35 @@ export class SessionSdkHost {
 					}
 					break;
 				}
+				case "session_activate": {
+					const id = requiredString(frame, "id");
+					const requestedSession = optionalString(frame, "sessionId");
+					const requestedGeneration = frame.endpointGeneration;
+					if (
+						requestedGeneration !== undefined &&
+						(typeof requestedGeneration !== "number" ||
+							!Number.isSafeInteger(requestedGeneration) ||
+							requestedGeneration <= 0)
+					)
+						throw invalidFrame("endpointGeneration must be a positive integer.");
+					// A request addressed to another session is refused before any
+					// activation authority is consulted.
+					const status: SessionActivationOutcome | "session_mismatch" =
+						requestedSession !== undefined && requestedSession !== this.#options.sessionId
+							? "session_mismatch"
+							: await this.activate(requestedGeneration as number | undefined);
+					const ok = status === "activated" || status === "already";
+					await this.#send(connectionId, {
+						type: "session_activate_result",
+						id,
+						ok,
+						status,
+						sessionId: this.#options.sessionId,
+						generation: this.events.generation,
+						...(ok ? {} : { error: { code: status, message: ACTIVATION_MESSAGES[status] } }),
+					});
+					break;
+				}
 				case "event_replay": {
 					const id = requiredString(frame, "id");
 					const rawGeneration =

package/src/sdk/lifecycle-session.ts

@@ -24,6 +24,12 @@ export type CreateLifecycleAgentSessionOptions = CreateAgentSessionOptions & {
 	 * the manager's short default ceiling.
 	 */
 	mcpStartupTimeoutMs?: number;
+	/**
+	 * The broker-issued readiness intent from this session's launch request.
+	 * `deferred` prepares the session: it holds endpoint authority and publishes
+	 * a prepared signal instead of readiness until it is explicitly activated.
+	 */
+	readiness?: "immediate" | "deferred";
 };
 
 /** Internal lifecycle-only session construction with an owner-bound SDK startup result. */
@@ -31,9 +37,9 @@ export async function createLifecycleAgentSession(
 	options: CreateLifecycleAgentSessionOptions = {},
 ): Promise<CreateLifecycleAgentSessionResult> {
 	const rollback = new SdkStartupRollbackTracker();
-	const capability = new SdkStartupCapability(rollback);
+	const capability = new SdkStartupCapability(rollback, options.readiness ?? "immediate");
 	try {
-		const { mcpStartupTimeoutMs, ...sessionOptions } = options;
+		const { mcpStartupTimeoutMs, readiness: _readiness, ...sessionOptions } = options;
 		const internalOptions = {
 			...sessionOptions,
 			[lifecycleStartupCapabilityOption]: capability,

package/src/sdk/protocol/operation-inventory.generated.json

@@ -2329,6 +2329,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:extendStartupTurnBarrier",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal CLI startup-readiness fence composition, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:constructor",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
@@ -2560,6 +2571,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:registerToolSessionTransitionCleanup",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal tool transition cleanup registration for shared artifact-manager ownership, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:getAsyncJobSnapshot",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/session-activation.ts

@@ -0,0 +1,127 @@
+/**
+ * The activation exchange a prepared session answers, and nothing else.
+ *
+ * A prepared session holds discoverable endpoint authority while its readiness
+ * stays withheld; activation is the one request that asks it to publish that
+ * readiness. Every caller shares this exchange whatever proved the endpoint
+ * authority beforehand: the `gjc notify activate-thread` CLI resolves it from
+ * the local session index, and the Coordinator resolves it from the broker's
+ * incarnation-bound binding.
+ *
+ * It lives outside `sdk/bus` on purpose. The existing-thread module reaches the
+ * chat-daemon and settings graph to prove a Slack binding, and the Coordinator
+ * MCP entrypoint may not reach that graph at all, so the exchange the machine
+ * entrypoint needs carries no notification, daemon, or settings dependency.
+ */
+
+import { SdkClientError } from "./client/client";
+
+export type SessionActivationErrorCode =
+	| "session_not_live"
+	| "not_prepared"
+	| "not_bound"
+	| "activation_unavailable"
+	| "activation_outcome_unknown";
+
+/** A fail-closed rejection while activating a prepared session. */
+export class SessionActivationError extends Error {
+	constructor(
+		readonly code: SessionActivationErrorCode,
+		message: string,
+	) {
+		super(message);
+		this.name = "SessionActivationError";
+	}
+}
+
+/** Safe confirmation of an activation. It carries identifiers only. */
+export interface ActivatedPreparedSession {
+	sessionId: string;
+	endpointGeneration: number;
+	status: "activated" | "already";
+}
+
+/** The narrow transport surface activation needs from an SDK connection. */
+export interface PreparedSessionActivationClient {
+	request(frame: Record<string, unknown>): Promise<Record<string, unknown>>;
+	close(): Promise<void>;
+}
+
+/**
+ * Ask one already-connected session to publish the readiness it withheld.
+ *
+ * The frame names the exact session and endpoint generation, and the answer is
+ * accepted only when it proves both, so a replacement session can never be
+ * activated in place of the requested one. Activation is idempotent: an exact
+ * retry answers `already` without a second readiness signal.
+ */
+export async function requestPreparedSessionActivation(
+	client: PreparedSessionActivationClient,
+	sessionId: string,
+	endpointGeneration: number,
+): Promise<ActivatedPreparedSession> {
+	try {
+		const answer = await client.request({
+			type: "session_activate",
+			sessionId,
+			endpointGeneration,
+		});
+		return interpretActivationAnswer(answer, sessionId, endpointGeneration);
+	} catch (error) {
+		throw activationFailure(error);
+	}
+}
+
+function interpretActivationAnswer(
+	answer: Record<string, unknown>,
+	sessionId: string,
+	endpointGeneration: number,
+): ActivatedPreparedSession {
+	const status = answer.status;
+	if (
+		answer.type !== "session_activate_result" ||
+		answer.ok !== true ||
+		answer.sessionId !== sessionId ||
+		answer.generation !== endpointGeneration ||
+		(status !== "activated" && status !== "already")
+	)
+		throw new SessionActivationError(
+			"activation_outcome_unknown",
+			"The session answered an activation that does not match the request; rerun it to observe the settled state.",
+		);
+	return { sessionId, endpointGeneration, status };
+}
+
+/**
+ * Translate a failed activation by what it proves.
+ *
+ * A refused status is definitive: the session decided and published nothing. A
+ * transport failure after the request was sent is not, because the session may
+ * have activated before the answer was lost; an exact retry then answers
+ * `already` rather than publishing a second readiness signal.
+ */
+function activationFailure(error: unknown): SessionActivationError {
+	if (error instanceof SessionActivationError) return error;
+	const code = error instanceof SdkClientError ? error.code : undefined;
+	if (code === "not_authorized")
+		return new SessionActivationError(
+			"not_bound",
+			"The session is prepared for an existing thread but no binding has been applied yet.",
+		);
+	if (code === "not_prepared")
+		return new SessionActivationError("not_prepared", "The session is not prepared for activation.");
+	if (code === "generation_changed" || code === "session_mismatch")
+		return new SessionActivationError(
+			"session_not_live",
+			"The session endpoint generation changed before activation; rerun it against the current session.",
+		);
+	if (code === "authority_unavailable")
+		return new SessionActivationError(
+			"activation_unavailable",
+			"The session could not read its activation authority.",
+		);
+	return new SessionActivationError(
+		"activation_outcome_unknown",
+		"The session did not answer the activation; rerun it to observe the settled state.",
+	);
+}