@agentuity/core 2.0.11 → 2.0.12

package/src/services/coder/types.ts

@@ -115,11 +115,11 @@ export const CoderWorkspaceDetailSchema = z
 		repoCount: z.number().describe('Number of repositories'),
 		savedSkillIds: z.array(z.string()).describe('Saved skill IDs in workspace'),
 		skillBucketIds: z.array(z.string()).describe('Skill bucket IDs in workspace'),
-		agentSlugs: z
+		enabledAgents: z
 			.array(z.string())
 			.optional()
 			.default([])
-			.describe('Published custom agent slugs in workspace'),
+			.describe('Effective agent roster stored on the workspace'),
 		selectionCount: z.number().describe('Total number of selections'),
 		createdAt: z.string().describe('Creation timestamp (ISO-8601)'),
 		updatedAt: z.string().describe('Last update timestamp (ISO-8601)'),
@@ -133,7 +133,7 @@ export const CoderCustomAgentThinkingLevelSchema = z
 	.describe('Thinking level override for a custom agent');
 export type CoderCustomAgentThinkingLevel = z.infer<typeof CoderCustomAgentThinkingLevelSchema>;
 
-export const CODER_CUSTOM_AGENT_PI_TOOLS = [
+export const CODER_CUSTOM_AGENT_TOOLS = [
 	'read',
 	'ls',
 	'find',
@@ -143,17 +143,17 @@ export const CODER_CUSTOM_AGENT_PI_TOOLS = [
 	'edit',
 ] as const;
 
-export const CoderCustomAgentPiToolSchema = z
-	.enum(CODER_CUSTOM_AGENT_PI_TOOLS)
+export const CoderCustomAgentToolSchema = z
+	.enum(CODER_CUSTOM_AGENT_TOOLS)
 	.describe('Workspace tool available to a standalone custom agent');
-export type CoderCustomAgentPiTool = z.infer<typeof CoderCustomAgentPiToolSchema>;
+export type CoderCustomAgentTool = z.infer<typeof CoderCustomAgentToolSchema>;
 
-export const CoderCustomAgentPiToolResponseSchema = z
-	.union([CoderCustomAgentPiToolSchema, z.string()])
-	.describe('Pi workspace tool granted to a standalone custom agent');
-export type CoderCustomAgentPiToolResponse = z.infer<typeof CoderCustomAgentPiToolResponseSchema>;
+export const CoderCustomAgentToolResponseSchema = z
+	.union([CoderCustomAgentToolSchema, z.string()])
+	.describe('Workspace tool granted to a standalone custom agent');
+export type CoderCustomAgentToolResponse = z.infer<typeof CoderCustomAgentToolResponseSchema>;
 
-export const CODER_CUSTOM_AGENT_HUB_TOOLS = [
+export const CODER_CUSTOM_AGENT_SERVICE_TOOLS = [
 	'session_dashboard',
 	'memory_service_search',
 	'memory_service_store',
@@ -198,15 +198,17 @@ export const CODER_CUSTOM_AGENT_HUB_TOOLS = [
 	'coord_spawn_workers',
 ] as const;
 
-export const CoderCustomAgentHubToolSchema = z
-	.enum(CODER_CUSTOM_AGENT_HUB_TOOLS)
-	.describe('Hub-managed tool available to a standalone custom agent');
-export type CoderCustomAgentHubTool = z.infer<typeof CoderCustomAgentHubToolSchema>;
+export const CoderCustomAgentServiceToolSchema = z
+	.enum(CODER_CUSTOM_AGENT_SERVICE_TOOLS)
+	.describe('Service tool available to a standalone custom agent');
+export type CoderCustomAgentServiceTool = z.infer<typeof CoderCustomAgentServiceToolSchema>;
 
-export const CoderCustomAgentHubToolResponseSchema = z
-	.union([CoderCustomAgentHubToolSchema, z.string()])
-	.describe('Hub-managed tool granted to a standalone custom agent');
-export type CoderCustomAgentHubToolResponse = z.infer<typeof CoderCustomAgentHubToolResponseSchema>;
+export const CoderCustomAgentServiceToolResponseSchema = z
+	.union([CoderCustomAgentServiceToolSchema, z.string()])
+	.describe('Service tool granted to a standalone custom agent');
+export type CoderCustomAgentServiceToolResponse = z.infer<
+	typeof CoderCustomAgentServiceToolResponseSchema
+>;
 
 export const CoderCustomAgentSnapshotSchema = z
 	.object({
@@ -221,15 +223,19 @@ export const CoderCustomAgentSnapshotSchema = z
 		headlessCompatible: z
 			.boolean()
 			.describe('Whether the custom agent is safe for non-interactive callers'),
-		piTools: z
-			.array(CoderCustomAgentPiToolResponseSchema)
-			.describe('Pi workspace tools granted to the custom agent'),
-		hubToolNames: z
-			.array(CoderCustomAgentHubToolResponseSchema)
-			.describe('Hub-managed tools granted to the custom agent'),
+		tools: z
+			.array(CoderCustomAgentToolResponseSchema)
+			.describe('Workspace tools granted to the custom agent'),
+		serviceTools: z
+			.array(CoderCustomAgentServiceToolResponseSchema)
+			.describe('Service tools granted to the custom agent'),
 		savedSkills: z
 			.array(CoderSkillRefSchema)
 			.describe('Frozen saved-skill refs attached to the custom agent snapshot'),
+		companionAgents: z
+			.array(z.string())
+			.default([])
+			.describe('Companion agents auto-included alongside this custom agent'),
 	})
 	.passthrough()
 	.describe('Custom agent snapshot returned by coder hub');
@@ -316,6 +322,20 @@ export const CoderWorkspaceListResponseSchema = z
 	.describe('Response payload for listing workspaces');
 export type CoderWorkspaceListResponse = z.infer<typeof CoderWorkspaceListResponseSchema>;
 
+function hasWorkspaceSelections(input: {
+	repos?: unknown[];
+	savedSkillIds?: unknown[];
+	skillBucketIds?: unknown[];
+	enabledAgents?: unknown[];
+}): boolean {
+	return (
+		(input.repos?.length ?? 0) > 0 ||
+		(input.savedSkillIds?.length ?? 0) > 0 ||
+		(input.skillBucketIds?.length ?? 0) > 0 ||
+		(input.enabledAgents?.length ?? 0) > 0
+	);
+}
+
 export const CoderCreateWorkspaceRequestSchema = z
 	.object({
 		name: z.string().describe('Workspace name'),
@@ -324,7 +344,13 @@ export const CoderCreateWorkspaceRequestSchema = z
 		repos: z.array(CoderSessionRepositoryRefSchema).optional().describe('Repositories'),
 		savedSkillIds: z.array(z.string()).optional().describe('Saved skill IDs'),
 		skillBucketIds: z.array(z.string()).optional().describe('Skill bucket IDs'),
-		agentSlugs: z.array(z.string()).optional().describe('Published custom agent slugs'),
+		enabledAgents: z
+			.array(z.string())
+			.optional()
+			.describe('Effective agent roster to store on the workspace'),
+	})
+	.refine(hasWorkspaceSelections, {
+		message: 'A workspace needs at least one repo, saved skill, skill bucket, or agent',
 	})
 	.describe('Request body for creating a workspace');
 export type CoderCreateWorkspaceRequest = z.infer<typeof CoderCreateWorkspaceRequestSchema>;
@@ -343,18 +369,22 @@ export const CoderCreateCustomAgentRequestSchema = z
 			.boolean()
 			.optional()
 			.describe('Whether the custom agent is safe for non-interactive callers'),
-		piTools: z
-			.array(CoderCustomAgentPiToolSchema)
+		tools: z
+			.array(CoderCustomAgentToolSchema)
 			.optional()
-			.describe('Pi workspace tools to grant to the custom agent'),
-		hubToolNames: z
-			.array(CoderCustomAgentHubToolSchema)
+			.describe('Workspace tools to grant to the custom agent'),
+		serviceTools: z
+			.array(CoderCustomAgentServiceToolSchema)
 			.optional()
-			.describe('Hub-managed tools to grant to the custom agent'),
+			.describe('Service tools to grant to the custom agent'),
 		savedSkillIds: z
 			.array(z.string())
 			.optional()
 			.describe('Saved skill row ids to snapshot onto the custom agent'),
+		companionAgents: z
+			.array(z.string())
+			.optional()
+			.describe('Agent names to auto-include alongside this custom agent'),
 	})
 	.describe('Request body for creating a custom agent draft');
 export type CoderCreateCustomAgentRequest = z.infer<typeof CoderCreateCustomAgentRequestSchema>;
@@ -373,18 +403,22 @@ export const CoderUpdateCustomAgentRequestSchema = z
 			.boolean()
 			.optional()
 			.describe('Whether the custom agent is safe for non-interactive callers'),
-		piTools: z
-			.array(CoderCustomAgentPiToolSchema)
+		tools: z
+			.array(CoderCustomAgentToolSchema)
 			.optional()
-			.describe('Pi workspace tools to grant to the custom agent'),
-		hubToolNames: z
-			.array(CoderCustomAgentHubToolSchema)
+			.describe('Workspace tools to grant to the custom agent'),
+		serviceTools: z
+			.array(CoderCustomAgentServiceToolSchema)
 			.optional()
-			.describe('Hub-managed tools to grant to the custom agent'),
+			.describe('Service tools to grant to the custom agent'),
 		savedSkillIds: z
 			.array(z.string())
 			.optional()
 			.describe('Saved skill row ids to snapshot onto the custom agent'),
+		companionAgents: z
+			.array(z.string())
+			.optional()
+			.describe('Agent names to auto-include alongside this custom agent'),
 	})
 	.describe('Request body for updating a custom agent draft');
 export type CoderUpdateCustomAgentRequest = z.infer<typeof CoderUpdateCustomAgentRequestSchema>;
@@ -447,10 +481,10 @@ export const CoderCreateSessionRequestSchema = z
 		workflowMode: CoderWorkflowModeSchema.optional().describe('Workflow execution mode'),
 		loop: CoderSessionLoopConfigSchema.optional().describe('Loop mode settings for the session'),
 		tags: z.array(z.string()).optional().describe('Tags applied to the session for filtering'),
-		agentSlugs: z
+		enabledAgents: z
 			.array(z.string())
 			.optional()
-			.describe('Published custom agent slugs to include in the session'),
+			.describe('Enabled agent roster to include in the session'),
 		savedSkillIds: z
 			.array(z.string())
 			.optional()
@@ -486,6 +520,59 @@ export const CoderCreateSessionRequestSchema = z
 	.describe('Request body for creating a coder session');
 export type CoderCreateSessionRequest = z.infer<typeof CoderCreateSessionRequestSchema>;
 
+function inferCoderAgentBuilderSessionMode(input: {
+	mode?: 'new' | 'edit' | 'from_session';
+	sourceSessionId?: string;
+	targetAgentId?: string;
+	targetAgentSlug?: string;
+}): 'new' | 'edit' | 'from_session' {
+	if (input.mode) return input.mode;
+	if (input.sourceSessionId) return 'from_session';
+	if (input.targetAgentId || input.targetAgentSlug) return 'edit';
+	return 'new';
+}
+
+export const CoderCreateAgentBuilderSessionRequestSchema = z
+	.object({
+		label: z.string().optional().describe('Builder session label override'),
+		prompt: z.string().optional().describe('Optional user focus for the builder session kickoff'),
+		mode: z
+			.enum(['new', 'edit', 'from_session'])
+			.optional()
+			.describe('Builder launch mode override'),
+		visibility: CoderSessionVisibilitySchema.optional().describe('Builder session visibility'),
+		sourceSessionId: z
+			.string()
+			.optional()
+			.describe('Source session identifier for build-from-session launches'),
+		targetAgentId: z
+			.string()
+			.optional()
+			.describe('Target custom-agent identifier for edit launches'),
+		targetAgentSlug: z.string().optional().describe('Target custom-agent slug for edit launches'),
+	})
+	.superRefine((value, ctx) => {
+		const mode = inferCoderAgentBuilderSessionMode(value);
+		if (mode === 'from_session' && !value.sourceSessionId?.trim()) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['sourceSessionId'],
+				message: 'sourceSessionId is required for from-session builder launches.',
+			});
+		}
+		if (mode === 'edit' && !value.targetAgentId?.trim() && !value.targetAgentSlug?.trim()) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['targetAgentId'],
+				message: 'targetAgentId or targetAgentSlug is required for edit launches.',
+			});
+		}
+	})
+	.describe('Request body for creating an agent-builder session');
+export type CoderCreateAgentBuilderSessionRequest = z.infer<
+	typeof CoderCreateAgentBuilderSessionRequestSchema
+>;
+
 export const CoderUpdateSessionRequestSchema = z
 	.object({
 		label: z.string().optional().describe('Updated session label'),
@@ -495,10 +582,10 @@ export const CoderUpdateSessionRequestSchema = z
 		workflowMode: CoderWorkflowModeSchema.optional().describe('Updated workflow mode'),
 		loop: CoderSessionLoopConfigSchema.optional().describe('Updated loop mode configuration'),
 		tags: z.array(z.string()).optional().describe('Updated set of tags for the session'),
-		agentSlugs: z
+		enabledAgents: z
 			.array(z.string())
 			.optional()
-			.describe('Updated published custom agent slugs included in the session'),
+			.describe('Updated enabled agent roster for the session'),
 		skills: z
 			.array(CoderSkillRefSchema)
 			.optional()
@@ -540,6 +627,126 @@ export const CoderSessionWorkspaceSchema = z
 	.describe('Workspace associated with a coder session');
 export type CoderSessionWorkspace = z.infer<typeof CoderSessionWorkspaceSchema>;
 
+export const CoderAgentBuilderSessionModeSchema = z
+	.enum(['new', 'edit', 'from_session'])
+	.describe('Agent-builder launch mode for a builder session');
+export type CoderAgentBuilderSessionMode = z.infer<typeof CoderAgentBuilderSessionModeSchema>;
+
+export const CoderAgentBuilderActionKindSchema = z
+	.enum(['create_draft', 'update_draft', 'publish'])
+	.describe('Durable builder action emitted by an agent-builder session');
+export type CoderAgentBuilderActionKind = z.infer<typeof CoderAgentBuilderActionKindSchema>;
+
+export const CoderAgentBuilderSourceSessionSchema = z
+	.object({
+		sessionId: z.string().describe('Source session identifier linked to the builder session'),
+		label: z.string().optional().describe('Source session label when available'),
+	})
+	.describe('Source session reference used by agent-builder flows');
+export type CoderAgentBuilderSourceSession = z.infer<typeof CoderAgentBuilderSourceSessionSchema>;
+
+export const CoderAgentBuilderTargetAgentSchema = z
+	.object({
+		agentId: z.string().optional().describe('Target custom-agent identifier when editing'),
+		slug: z.string().describe('Target custom-agent slug'),
+		displayName: z.string().optional().describe('Target custom-agent display name'),
+	})
+	.describe('Target custom-agent reference for agent-builder edit flows');
+export type CoderAgentBuilderTargetAgent = z.infer<typeof CoderAgentBuilderTargetAgentSchema>;
+
+export const CoderAgentBuilderProposalSchema = z
+	.object({
+		slug: z.string().optional().describe('Proposed custom-agent slug'),
+		displayName: z.string().optional().describe('Proposed custom-agent name'),
+		description: z.string().optional().describe('Proposed custom-agent description'),
+		instructions: z.string().optional().describe('Proposed custom-agent system prompt'),
+		model: z.string().optional().describe('Proposed model override'),
+		thinkingLevel: CoderCustomAgentThinkingLevelSchema.optional().describe(
+			'Proposed thinking level override'
+		),
+		headlessCompatible: z
+			.boolean()
+			.optional()
+			.describe('Whether the proposed agent is safe for non-interactive callers'),
+		tools: z
+			.array(CoderCustomAgentToolResponseSchema)
+			.default([])
+			.describe('Proposed workspace tools for the agent'),
+		serviceTools: z
+			.array(CoderCustomAgentServiceToolResponseSchema)
+			.default([])
+			.describe('Proposed service tools for the agent'),
+		savedSkills: z
+			.array(CoderSkillRefSchema)
+			.default([])
+			.describe('Proposed frozen skill refs to attach'),
+		companionAgents: z
+			.array(z.string())
+			.default([])
+			.describe('Proposed companion agents to auto-include'),
+	})
+	.passthrough()
+	.describe('Session-scoped agent-builder proposal state');
+export type CoderAgentBuilderProposal = z.infer<typeof CoderAgentBuilderProposalSchema>;
+
+export const CoderAgentBuilderDurableStateSchema = z
+	.object({
+		draftAgentId: z.string().optional().describe('Linked draft custom-agent identifier'),
+		draftAgentSlug: z.string().optional().describe('Linked draft custom-agent slug'),
+		lastPublishedVersion: z
+			.number()
+			.int()
+			.optional()
+			.describe('Latest published version created through the builder flow'),
+	})
+	.describe('Durable agent-library state associated with a builder session');
+export type CoderAgentBuilderDurableState = z.infer<typeof CoderAgentBuilderDurableStateSchema>;
+
+export const CoderAgentBuilderActionStateSchema = z
+	.object({
+		kind: CoderAgentBuilderActionKindSchema.describe('Last durable builder action'),
+		status: z.enum(['completed', 'failed']).describe('Result of the last durable builder action'),
+		occurredAt: z.string().describe('Timestamp of the last durable builder action'),
+		message: z.string().optional().describe('Human-readable builder action result summary'),
+		agentId: z.string().optional().describe('Affected custom-agent identifier'),
+		agentSlug: z.string().optional().describe('Affected custom-agent slug'),
+		publishedVersion: z
+			.number()
+			.int()
+			.optional()
+			.describe('Published version number when publish succeeded'),
+	})
+	.describe('Latest durable action emitted by a builder session');
+export type CoderAgentBuilderActionState = z.infer<typeof CoderAgentBuilderActionStateSchema>;
+
+export const CoderAgentBuilderSessionSummarySchema = z
+	.object({
+		mode: CoderAgentBuilderSessionModeSchema.describe('Builder session mode'),
+		sourceSession: CoderAgentBuilderSourceSessionSchema.optional().describe(
+			'Linked source session when the builder was launched from an existing session'
+		),
+		targetAgent: CoderAgentBuilderTargetAgentSchema.optional().describe(
+			'Target agent baseline when the builder is editing an existing custom agent'
+		),
+		durable: CoderAgentBuilderDurableStateSchema.optional().describe(
+			'Linked durable draft/publish state'
+		),
+		lastAction: CoderAgentBuilderActionStateSchema.optional().describe(
+			'Most recent durable builder action'
+		),
+	})
+	.describe('Projected builder-session summary returned in session listings');
+export type CoderAgentBuilderSessionSummary = z.infer<typeof CoderAgentBuilderSessionSummarySchema>;
+
+export const CoderAgentBuilderSessionStateSchema = CoderAgentBuilderSessionSummarySchema.extend({
+	proposal: CoderAgentBuilderProposalSchema.optional().describe(
+		'Full builder proposal state projected in session detail responses'
+	),
+})
+	.passthrough()
+	.describe('Full builder-session state returned in session details');
+export type CoderAgentBuilderSessionState = z.infer<typeof CoderAgentBuilderSessionStateSchema>;
+
 export const CoderSessionListItemSchema = z
 	.object({
 		sessionId: z.string().describe('Unique session identifier'),
@@ -580,11 +787,14 @@ export const CoderSessionListItemSchema = z
 		participantCount: z.number().describe('Total number of participants in the session'),
 		tags: z.array(z.string()).describe('Tag values attached to the session'),
 		skills: z.array(CoderSkillRefSchema).describe('Skills attached to the session'),
-		agentSlugs: z
+		enabledAgents: z
 			.array(z.string())
 			.optional()
 			.default([])
-			.describe('Published custom agent slugs attached to the session'),
+			.describe('Enabled agent roster attached to the session'),
+		builder: CoderAgentBuilderSessionSummarySchema.optional().describe(
+			'Projected builder-session summary when this session is an agent-builder flow'
+		),
 		defaultAgent: z.string().optional().describe('Default agent assigned to session operations'),
 		bucket: CoderSessionBucketSchema.describe('Derived bucket for session listing'),
 		runtimeAvailable: z.boolean().describe('Whether runtime is currently reachable'),
@@ -616,6 +826,9 @@ export const CoderSessionSchema = CoderSessionListItemSchema.extend({
 		.string()
 		.optional()
 		.describe('Last update timestamp for session metadata (ISO-8601)'),
+	builder: CoderAgentBuilderSessionStateSchema.optional().describe(
+		'Full builder-session state when this session is an agent-builder flow'
+	),
 	// These fields are present in list items but may be absent in detail responses
 	lastActivityAt: z.string().optional().describe('Timestamp of most recent activity (ISO-8601)'),
 	taskCount: z.number().optional().describe('Number of tasks associated with the session'),

package/src/services/coder/websocket.ts

@@ -70,7 +70,7 @@ import type {
 	ConnectionParams,
 	ServerMessage,
 } from './protocol.ts';
-import { CoderHubInitMessageSchema } from './protocol.ts';
+import { CoderHubInitMessageSchema, parseServerMessage } from './protocol.ts';
 import { normalizeCoderUrl } from './util.ts';
 
 /**
@@ -118,6 +118,11 @@ export const CoderHubWebSocketOptionsSchema = z.object({
 	task: z.string().optional().describe('Initial task for driver mode'),
 	/** Human-readable session label */
 	label: z.string().optional().describe('Session label'),
+	/** Observer event filters to request during the initial connection. */
+	subscribe: z
+		.array(z.string())
+		.optional()
+		.describe('Observer event filters to request during connection setup'),
 	/** Client origin (web, desktop, tui, sdk) */
 	origin: z.enum(['web', 'desktop', 'tui', 'sdk']).optional().describe('Client origin'),
 	/** Driver mode: 'rpc' for RPC bridge driver */
@@ -198,7 +203,13 @@ export const CoderHubWebSocketError = StructuredError('CoderHubWebSocketError')<
 		| 'response_timeout'
 		| 'invalid_response';
 	sessionId?: string;
+	serverCode?: string;
+	serverMessage?: string;
+	serverMessageType?: 'connection_rejected' | 'protocol_error';
+	closeCode?: number;
+	closeReason?: string;
 }>();
+export type CoderHubWebSocketErrorInstance = InstanceType<typeof CoderHubWebSocketError>;
 
 interface PendingRequest {
 	resolve: (response: CoderHubResponse) => void;
@@ -270,6 +281,7 @@ export class CoderHubWebSocketClient {
 		parentSessionId: string;
 		task: string;
 		label: string;
+		subscribe: string[];
 		origin: 'web' | 'desktop' | 'tui' | 'sdk';
 		driverMode: 'rpc' | undefined;
 		driverInstanceId: string;
@@ -317,6 +329,7 @@ export class CoderHubWebSocketClient {
 			parentSessionId: options.parentSessionId ?? '',
 			task: options.task ?? '',
 			label: options.label ?? '',
+			subscribe: options.subscribe ?? [],
 			origin: options.origin ?? 'sdk',
 			driverMode: options.driverMode,
 			driverInstanceId: options.driverInstanceId ?? '',
@@ -522,6 +535,57 @@ export class CoderHubWebSocketClient {
 		return `${Date.now()}-${++this.#messageId}`;
 	}
 
+	#buildHandshakeError(input: {
+		code: 'auth_failed' | 'connection_error';
+		message: string;
+		serverCode?: string;
+		serverMessage?: string;
+		serverMessageType?: 'connection_rejected' | 'protocol_error';
+		closeCode?: number;
+		closeReason?: string;
+	}): CoderHubWebSocketErrorInstance {
+		return new CoderHubWebSocketError({
+			code: input.code,
+			message: input.message,
+			sessionId: this.sessionId,
+			serverCode: input.serverCode,
+			serverMessage: input.serverMessage,
+			serverMessageType: input.serverMessageType,
+			closeCode: input.closeCode,
+			closeReason: input.closeReason,
+		});
+	}
+
+	#markReady(input?: {
+		initMessage?: CoderHubInitMessage;
+		firstMessage?: ServerMessage;
+		sendBootstrapReady?: boolean;
+	}): void {
+		this.#authenticated = true;
+		this.#initMessage = input?.initMessage ?? null;
+		this.#sessionId =
+			input?.initMessage?.sessionId ??
+			(input?.firstMessage && 'sessionId' in input.firstMessage
+				? input.firstMessage.sessionId
+				: undefined) ??
+			this.#options.sessionId ??
+			null;
+		this.#reconnectAttempts = 0;
+		this.#setState('connected');
+		this.#startHeartbeat();
+		if (input?.initMessage) {
+			this.#options.onInit(input.initMessage);
+		}
+		if (input?.sendBootstrapReady && this.#ws?.readyState === WebSocket.OPEN) {
+			this.#ws.send(JSON.stringify({ type: 'bootstrap_ready' }));
+		}
+		this.#flushMessageQueue();
+		this.#options.onOpen();
+		if (input?.firstMessage) {
+			this.#options.onMessage(input.firstMessage);
+		}
+	}
+
 	#setState(state: CoderHubWebSocketState): void {
 		if (this.#state !== state) {
 			this.#state = state;
@@ -589,6 +653,8 @@ export class CoderHubWebSocketClient {
 			parent: this.#options.parentSessionId || undefined,
 			task: this.#options.task || undefined,
 			label: this.#options.label || undefined,
+			subscribe:
+				this.#options.subscribe.length > 0 ? this.#options.subscribe.join(',') : undefined,
 			orgId: this.#options.orgId || undefined,
 			origin: this.#options.origin || undefined,
 			driverMode: this.#options.driverMode || undefined,
@@ -601,6 +667,9 @@ export class CoderHubWebSocketClient {
 				params.set(key, String(value));
 			}
 		}
+		if (this.#options.apiKey) {
+			params.set('api_key', this.#options.apiKey);
+		}
 
 		const queryString = params.toString();
 		return queryString ? `${wsUrl}?${queryString}` : wsUrl;
@@ -642,12 +711,16 @@ export class CoderHubWebSocketClient {
 		ws.onopen = () => {
 			if (ws !== this.#ws) return;
 			this.#setState('authenticating');
-			ws.send(
-				JSON.stringify({
-					authorization: this.#options.apiKey,
-					org_id: this.#options.orgId,
-				})
-			);
+			if (this.#options.apiKey || this.#options.orgId) {
+				const bootstrapPayload: { authorization?: string; org_id?: string } = {};
+				if (this.#options.apiKey) {
+					bootstrapPayload.authorization = this.#options.apiKey;
+				}
+				if (this.#options.orgId) {
+					bootstrapPayload.org_id = this.#options.orgId;
+				}
+				ws.send(JSON.stringify(bootstrapPayload));
+			}
 		};
 
 		ws.onmessage = (event: MessageEvent) => {
@@ -685,10 +758,12 @@ export class CoderHubWebSocketClient {
 					if (msg.type === 'connection_rejected' || msg.type === 'protocol_error') {
 						this.#setState('closed');
 						this.#options.onError(
-							new CoderHubWebSocketError({
-								message: `Connection rejected: ${msg.message ?? msg.code ?? 'Unknown error'}`,
+							this.#buildHandshakeError({
 								code: 'auth_failed',
-								sessionId: this.sessionId,
+								message: `Connection rejected: ${msg.message ?? msg.code ?? 'Unknown error'}`,
+								serverCode: msg.code,
+								serverMessage: msg.message,
+								serverMessageType: msg.type,
 							})
 						);
 						this.#intentionallyClosed = true;
@@ -700,15 +775,18 @@ export class CoderHubWebSocketClient {
 				const initResult = CoderHubInitMessageSchema.safeParse(parsed);
 				if (initResult.success) {
 					const initMsg = initResult.data;
-					this.#authenticated = true;
-					this.#initMessage = initMsg;
-					this.#sessionId = initMsg.sessionId ?? this.#options.sessionId ?? null;
-					this.#reconnectAttempts = 0;
-					this.#setState('connected');
-					this.#startHeartbeat();
-					this.#flushMessageQueue();
-					this.#options.onInit(initMsg);
-					this.#options.onOpen();
+					this.#markReady({
+						initMessage: initMsg,
+						sendBootstrapReady: this.#options.role === 'controller',
+					});
+					return;
+				}
+
+				if (this.#options.role === 'observer') {
+					const firstObserverMessage = parseServerMessage(parsed);
+					if (firstObserverMessage) {
+						this.#markReady({ firstMessage: firstObserverMessage });
+					}
 				}
 				return;
 			}
@@ -759,14 +837,31 @@ export class CoderHubWebSocketClient {
 			this.#clearTimers();
 			this.#setState('closed');
 
+			const wasAuthenticated = this.#authenticated;
+			const hadTerminalError = this.#intentionallyClosed;
+			const terminalClose = isTerminalCloseCode(event.code);
+
 			// Clear auth state for clean reconnect
 			this.#authenticated = false;
 			this.#initMessage = null;
 
-			if (isTerminalCloseCode(event.code)) {
+			if (terminalClose) {
 				this.#intentionallyClosed = true;
 			}
 
+			if (!wasAuthenticated && terminalClose && !hadTerminalError) {
+				this.#options.onError(
+					this.#buildHandshakeError({
+						code: 'connection_error',
+						message: `WebSocket closed before connection was ready (code ${event.code})${
+							event.reason ? `: ${event.reason}` : ''
+						}`,
+						closeCode: event.code,
+						closeReason: event.reason || undefined,
+					})
+				);
+			}
+
 			this.#options.onClose(event.code, event.reason);
 
 			if (!this.#intentionallyClosed) {
@@ -896,7 +991,11 @@ export async function* subscribeToCoderHub(
 		onError: (error) => {
 			if (
 				error instanceof CoderHubWebSocketError &&
-				(error.code === 'max_reconnects_exceeded' || error.code === 'auth_failed')
+				(error.code === 'max_reconnects_exceeded' ||
+					error.code === 'auth_failed' ||
+					(error.code === 'connection_error' &&
+						typeof error.closeCode === 'number' &&
+						isTerminalCloseCode(error.closeCode)))
 			) {
 				terminalError = error;
 				done = true;