@agentuity/coder 1.0.40 → 1.0.41

package/src/protocol.ts

@@ -1,22 +1,80 @@
-// ---- Init Message (Server → Client on connect) ----
+// Hub protocol types used by the Coder TUI package.
+// Keep the legacy exported names stable while modeling the newer hub envelopes.
 
 export interface HubToolDefinition {
 	name: string;
 	label: string;
 	description: string;
-	parameters: Record<string, unknown>; // JSON Schema object
+	parameters: Record<string, unknown>;
 	promptSnippet?: string;
 	promptGuidelines?: string | string[];
 }
 
-/** Command definition sent by Hub for agent routing slash commands. */
 export interface HubCommandDefinition {
 	name: string;
 	description: string;
 }
 
+export interface AckAction {
+	action: 'ACK';
+}
+
+export interface BlockAction {
+	action: 'BLOCK';
+	reason: string;
+}
+
+export interface ConfirmAction {
+	action: 'CONFIRM';
+	title: string;
+	message: string;
+	deny_reason?: string;
+}
+
+export interface NotifyAction {
+	action: 'NOTIFY';
+	message: string;
+	level?: 'info' | 'warning' | 'error';
+}
+
+export interface ReturnAction {
+	action: 'RETURN';
+	result: unknown;
+}
+
+export interface StatusAction {
+	action: 'STATUS';
+	key: string;
+	text?: string;
+}
+
+export interface SystemPromptAction {
+	action: 'SYSTEM_PROMPT';
+	systemPrompt: string;
+	mode?: 'replace' | 'prefix' | 'suffix';
+}
+
+export interface InjectMessageAction {
+	action: 'INJECT_MESSAGE';
+	message: {
+		role: 'user' | 'assistant';
+		content: string;
+	};
+}
+
+export type HubAction =
+	| AckAction
+	| BlockAction
+	| ConfirmAction
+	| NotifyAction
+	| ReturnAction
+	| StatusAction
+	| SystemPromptAction
+	| InjectMessageAction;
+
 export interface AgentDefinition {
 	name: string;
+	displayName?: string;
 	description: string;
 	systemPrompt: string;
 	model?: string;
@@ -41,10 +99,14 @@ export interface InitMessage {
 	commands?: HubCommandDefinition[];
 	agents?: AgentDefinition[];
 	config?: HubConfig;
+	model?: {
+		provider: string;
+		id: string;
+	};
+	thinkingLevel?: string;
+	task?: string;
 }
 
-// ---- Request Messages (Client → Server) ----
-
 export interface EventRequest {
 	id: string;
 	type: 'event';
@@ -60,7 +122,6 @@ export interface ToolRequest {
 	params: Record<string, unknown>;
 }
 
-/** Command request (Client -> Server) for slash command execution. */
 export interface CommandRequest {
 	id: string;
 	type: 'command';
@@ -70,68 +131,228 @@ export interface CommandRequest {
 
 export type HubRequest = EventRequest | ToolRequest | CommandRequest;
 
-// ---- Actions ----
+export interface SessionEntryMessage {
+	type: 'session_entry';
+	path: string;
+	line: string;
+}
 
-export interface AckAction {
-	action: 'ACK';
+export interface SessionWriteMessage {
+	type: 'session_write';
+	path: string;
+	content: string;
 }
 
-export interface BlockAction {
-	action: 'BLOCK';
-	reason: string;
+export interface RpcCommandMessage {
+	type: 'rpc_command';
+	command: Record<string, unknown>;
 }
 
-export interface ConfirmAction {
-	action: 'CONFIRM';
-	title: string;
-	message: string;
-	deny_reason?: string;
+export interface RpcUiResponseMessage {
+	type: 'rpc_ui_response';
+	id: string;
+	result: unknown;
 }
 
-export interface NotifyAction {
-	action: 'NOTIFY';
+export interface PingMessage {
+	type: 'ping';
+	timestamp: number;
+}
+
+export type HubClientMessage =
+	| HubRequest
+	| SessionEntryMessage
+	| SessionWriteMessage
+	| RpcCommandMessage
+	| RpcUiResponseMessage
+	| PingMessage;
+
+export interface HubResponse {
+	id: string;
+	actions: HubAction[];
+}
+
+export interface CoderHubStreamReadyMessage {
+	type: 'session_stream_ready';
+	streamId: string;
+	streamUrl: string;
+}
+
+export interface CoderHubSessionResumeMessage {
+	type: 'session_resume';
+	streamUrl: string;
+	streamId: string;
+	activePrdKey?: string;
+}
+
+export interface ConnectionRejectedMessage {
+	type: 'connection_rejected';
+	code: string;
 	message: string;
-	level?: 'info' | 'warning' | 'error';
+	sessionId?: string;
+	reconnectState?: string;
+	expiredAt?: number;
+	timestamp: number;
 }
 
-export interface ReturnAction {
-	action: 'RETURN';
-	result: unknown;
+export interface ConversationEntry {
+	type:
+		| 'message'
+		| 'thinking'
+		| 'tool_call'
+		| 'tool_result'
+		| 'task_result'
+		| 'turn'
+		| 'user_prompt';
+	agent?: string;
+	content?: string;
+	toolName?: string;
+	toolArgs?: Record<string, unknown>;
+	toolCallId?: string;
+	isError?: boolean;
+	taskId?: string;
+	timestamp: number;
 }
 
-export interface StatusAction {
-	action: 'STATUS';
-	key: string;
-	text?: string; // undefined = clear status
+export interface HydrationTaskState {
+	taskId: string;
+	agent: string;
+	status: 'running' | 'completed' | 'failed';
+	prompt: string;
+	duration?: number;
+	result?: string;
+	error?: string;
 }
 
-export interface SystemPromptAction {
-	action: 'SYSTEM_PROMPT';
-	systemPrompt: string;
-	mode?: 'replace' | 'prefix' | 'suffix';
+export interface SessionParticipant {
+	id: string;
+	role: 'lead' | 'observer' | 'controller';
+	transport: 'ws' | 'sse';
+	subscriptions: string[];
+	connectedAt: number;
+	lastActivity: number;
 }
 
-export interface InjectMessageAction {
-	action: 'INJECT_MESSAGE';
-	message: {
-		role: 'user' | 'assistant';
-		content: string;
+export interface SessionStreamBlock {
+	output: string;
+	thinking: string;
+}
+
+export interface SessionStreamProjection extends SessionStreamBlock {
+	tasks: Record<string, SessionStreamBlock>;
+}
+
+export interface SessionSnapshot {
+	sessionId: string;
+	label: string;
+	status: 'active' | 'paused' | 'shutdown' | 'archived' | 'error' | 'stopped';
+	createdAt: string;
+	mode: 'sandbox' | 'tui';
+	task?: string;
+	error?: string;
+	streamId?: string | null;
+	streamUrl?: string | null;
+	context: {
+		branch?: string;
+		workingDirectory?: string;
 	};
+	participants: SessionParticipant[];
+	tasks: Array<{
+		taskId: string;
+		agent: string;
+		status: 'running' | 'completed' | 'failed';
+		prompt: string;
+		duration?: number;
+		startedAt?: string;
+		completedAt?: string;
+	}>;
+	agentActivity: Record<
+		string,
+		{
+			name?: string;
+			status: string;
+			currentTool?: string;
+			currentToolArgs?: string;
+			toolCallCount: number;
+			lastActivity: number;
+			totalElapsed?: number;
+		}
+	>;
+	stream?: SessionStreamProjection;
+	tags?: string[];
+	defaultAgent?: string;
+	bucket?: 'running' | 'paused' | 'provisioning' | 'history';
+	runtimeAvailable?: boolean;
+	controlAvailable?: boolean;
+	historyOnly?: boolean;
 }
 
-export type HubAction =
-	| AckAction
-	| BlockAction
-	| ConfirmAction
-	| NotifyAction
-	| ReturnAction
-	| StatusAction
-	| SystemPromptAction
-	| InjectMessageAction;
+export interface CoderHubHydrationMessage {
+	type: 'session_hydration';
+	sessionId: string;
+	resumedAt: number;
+	entries: ConversationEntry[];
+	tasks: HydrationTaskState[];
+	stream?: SessionStreamProjection;
+	task?: string;
+	streamingState?: {
+		isStreaming?: boolean;
+		activeTasks?: Array<{
+			taskId: string;
+			agent: string;
+		}>;
+	};
+}
 
-// ---- Progress Tracking (Sub-Agent → Parent) ----
+export interface PresenceEventMessage {
+	type: 'presence';
+	event: 'session_join' | 'session_leave' | 'presence_update';
+	participant?: SessionParticipant;
+	participants?: SessionParticipant[];
+	sessionId: string;
+	timestamp: number;
+}
+
+export interface BroadcastEventMessage {
+	type: 'broadcast';
+	event: string;
+	data: Record<string, unknown>;
+	category?: string;
+	sessionId?: string;
+	timestamp?: number;
+}
+
+export interface RpcEventMessage {
+	type: 'rpc_event';
+	event: Record<string, unknown>;
+	timestamp: number;
+}
+
+export interface RpcResponseMessage {
+	type: 'rpc_response';
+	response: Record<string, unknown>;
+}
+
+export interface RpcUiRequestMessage {
+	type: 'rpc_ui_request';
+	id: string;
+	method: string;
+	params: Record<string, unknown>;
+}
+
+export type ServerMessage =
+	| InitMessage
+	| HubResponse
+	| CoderHubHydrationMessage
+	| CoderHubStreamReadyMessage
+	| CoderHubSessionResumeMessage
+	| ConnectionRejectedMessage
+	| PresenceEventMessage
+	| BroadcastEventMessage
+	| RpcEventMessage
+	| RpcResponseMessage
+	| RpcUiRequestMessage;
 
-/** Progress update from a running sub-agent */
 export interface AgentProgressUpdate {
 	agentName: string;
 	status:
@@ -146,12 +367,5 @@ export interface AgentProgressUpdate {
 	currentToolArgs?: string;
 	elapsed: number;
 	tokens?: { input: number; output: number; cost: number };
-	delta?: string; // Streaming token delta for thinking_delta / text_delta
-}
-
-// ---- Response Message (Server → Client) ----
-
-export interface HubResponse {
-	id: string;
-	actions: HubAction[];
+	delta?: string;
 }

package/src/remote-lifecycle.ts

@@ -0,0 +1,270 @@
+export type RemoteLifecyclePhase =
+	| 'connecting'
+	| 'hydrating'
+	| 'replaying'
+	| 'live'
+	| 'paused'
+	| 'resuming'
+	| 'reconnecting'
+	| 'disconnected';
+
+export type RemoteTransportState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+
+export interface RemoteLifecycleState {
+	sessionId: string;
+	label: string;
+	transport: RemoteTransportState;
+	phase: RemoteLifecyclePhase;
+	leadConnected: boolean | null;
+	isStreaming: boolean;
+	hydrationReceived: boolean;
+	streamId: string | null;
+	streamUrl: string | null;
+	lastError: string | null;
+}
+
+export interface RemoteLifecycleWorkingMessageUi {
+	setWorkingMessage(message?: string): void;
+}
+
+export type RemoteLifecycleEvent =
+	| { type: 'connect_start'; reconnect: boolean }
+	| { type: 'init'; sessionId?: string; label?: string }
+	| {
+			type: 'hydration';
+			leadConnected?: boolean;
+			isStreaming?: boolean;
+	  }
+	| { type: 'replay_event' }
+	| { type: 'replay_idle' }
+	| { type: 'live_signal'; isStreaming?: boolean }
+	| { type: 'session_resume'; streamId?: string | null; streamUrl?: string | null }
+	| { type: 'stream_ready'; streamId?: string | null; streamUrl?: string | null }
+	| { type: 'rpc_command_error'; error: string; paused: boolean }
+	| { type: 'local_resume_requested' }
+	| { type: 'connection_change'; state: 'reconnecting' | 'disconnected' };
+
+export function createRemoteLifecycleState(sessionId: string): RemoteLifecycleState {
+	return {
+		sessionId,
+		label: '',
+		transport: 'disconnected',
+		phase: 'disconnected',
+		leadConnected: null,
+		isStreaming: false,
+		hydrationReceived: false,
+		streamId: null,
+		streamUrl: null,
+		lastError: null,
+	};
+}
+
+function patchState(
+	state: RemoteLifecycleState,
+	patch: Partial<RemoteLifecycleState>
+): RemoteLifecycleState {
+	let changed = false;
+	const next = { ...state };
+
+	for (const [key, value] of Object.entries(patch)) {
+		const typedKey = key as keyof RemoteLifecycleState;
+		if (next[typedKey] !== value) {
+			changed = true;
+			(next[typedKey] as RemoteLifecycleState[keyof RemoteLifecycleState]) =
+				value as RemoteLifecycleState[keyof RemoteLifecycleState];
+		}
+	}
+
+	return changed ? next : state;
+}
+
+function resolveConnectedPhase(input: {
+	leadConnected: boolean | null;
+	isStreaming: boolean;
+}): RemoteLifecyclePhase {
+	if (input.isStreaming) return 'live';
+	if (input.leadConnected === false) return 'paused';
+	return 'live';
+}
+
+export function applyRemoteLifecycleEvent(
+	state: RemoteLifecycleState,
+	event: RemoteLifecycleEvent
+): RemoteLifecycleState {
+	switch (event.type) {
+		case 'connect_start':
+			return patchState(state, {
+				transport: event.reconnect ? 'reconnecting' : 'connecting',
+				phase: event.reconnect ? 'reconnecting' : 'connecting',
+				lastError: null,
+			});
+
+		case 'init':
+			return patchState(state, {
+				sessionId: event.sessionId || state.sessionId,
+				label: event.label || state.label,
+				transport: 'connected',
+				phase: 'hydrating',
+				lastError: null,
+			});
+
+		case 'hydration': {
+			const leadConnected =
+				typeof event.leadConnected === 'boolean' ? event.leadConnected : state.leadConnected;
+			const isStreaming =
+				typeof event.isStreaming === 'boolean' ? event.isStreaming : state.isStreaming;
+			return patchState(state, {
+				leadConnected,
+				isStreaming,
+				hydrationReceived: true,
+				transport: 'connected',
+				phase: resolveConnectedPhase({ leadConnected, isStreaming }),
+				lastError: null,
+			});
+		}
+
+		case 'replay_event':
+			if (state.transport !== 'connected') return state;
+			return patchState(state, {
+				phase: 'replaying',
+			});
+
+		case 'replay_idle':
+			if (state.phase !== 'replaying') return state;
+			return patchState(state, {
+				phase: resolveConnectedPhase({
+					leadConnected: state.leadConnected,
+					isStreaming: state.isStreaming,
+				}),
+			});
+
+		case 'live_signal':
+			return patchState(state, {
+				transport: 'connected',
+				phase: 'live',
+				leadConnected: true,
+				isStreaming:
+					typeof event.isStreaming === 'boolean' ? event.isStreaming : state.isStreaming,
+				lastError: null,
+			});
+
+		case 'session_resume':
+			return patchState(state, {
+				streamId: event.streamId ?? state.streamId,
+				streamUrl: event.streamUrl ?? state.streamUrl,
+				phase: 'resuming',
+				lastError: null,
+			});
+
+		case 'stream_ready':
+			return patchState(state, {
+				streamId: event.streamId ?? state.streamId,
+				streamUrl: event.streamUrl ?? state.streamUrl,
+			});
+
+		case 'rpc_command_error':
+			return patchState(state, {
+				lastError: event.error,
+				leadConnected: event.paused ? false : state.leadConnected,
+				isStreaming: event.paused ? false : state.isStreaming,
+				phase: event.paused ? 'paused' : state.phase,
+			});
+
+		case 'local_resume_requested':
+			return patchState(state, {
+				phase: 'resuming',
+				lastError: null,
+			});
+
+		case 'connection_change':
+			return patchState(state, {
+				transport: event.state,
+				phase: event.state,
+				isStreaming: false,
+			});
+	}
+}
+
+export function getRemoteLifecycleLabel(state: RemoteLifecycleState): string {
+	switch (state.phase) {
+		case 'connecting':
+			return 'Connecting';
+		case 'hydrating':
+			return 'Hydrating';
+		case 'replaying':
+			return 'Replaying';
+		case 'paused':
+			return 'Paused';
+		case 'resuming':
+			return 'Resuming';
+		case 'reconnecting':
+			return 'Reconnecting';
+		case 'disconnected':
+			return 'Disconnected';
+		case 'live':
+			return 'Live';
+	}
+}
+
+export function getRemoteLifecycleActivityLabel(state: RemoteLifecycleState): string | undefined {
+	switch (state.phase) {
+		case 'connecting':
+			return 'connecting to sandbox...';
+		case 'hydrating':
+			return 'hydrating remote session...';
+		case 'replaying':
+			return 'replaying remote history...';
+		case 'paused':
+			return 'sandbox paused';
+		case 'resuming':
+			return 'resuming sandbox...';
+		case 'reconnecting':
+			return 'reconnecting...';
+		case 'disconnected':
+			return state.lastError ? `disconnected: ${state.lastError}` : 'disconnected';
+		case 'live':
+			return undefined;
+	}
+}
+
+export function getRemoteLifecycleWorkingMessage(state: RemoteLifecycleState): string | undefined {
+	switch (state.phase) {
+		case 'connecting':
+			return 'Connecting to remote sandbox...';
+		case 'hydrating':
+			return 'Hydrating remote session...';
+		case 'replaying':
+			return 'Replaying remote history...';
+		case 'resuming':
+			return 'Resuming remote sandbox...';
+		case 'reconnecting':
+			return 'Connection lost - reconnecting...';
+		case 'paused':
+		case 'disconnected':
+		case 'live':
+			return undefined;
+	}
+}
+
+export function clearRemoteLifecycleWorkingMessage(
+	ui: RemoteLifecycleWorkingMessageUi,
+	lifecycleOwnsWorkingMessage: boolean
+): boolean {
+	if (lifecycleOwnsWorkingMessage) {
+		ui.setWorkingMessage();
+	}
+	return false;
+}
+
+export function syncRemoteLifecycleWorkingMessage(
+	state: RemoteLifecycleState,
+	ui: RemoteLifecycleWorkingMessageUi,
+	lifecycleOwnsWorkingMessage: boolean
+): boolean {
+	const working = getRemoteLifecycleWorkingMessage(state);
+	if (working) {
+		ui.setWorkingMessage(working);
+		return true;
+	}
+	return clearRemoteLifecycleWorkingMessage(ui, lifecycleOwnsWorkingMessage);
+}