@agentuity/coder 2.0.0-beta.1 → 2.0.0

package/src/protocol.ts

@@ -94,7 +94,13 @@ export interface HubConfig {
 
 export interface InitMessage {
 	type: 'init';
+	role: 'lead' | 'sub_agent' | 'controller';
 	sessionId?: string;
+	resume?: {
+		sessionFile: string;
+		piSessionId?: string;
+		cwd?: string;
+	};
 	tools?: HubToolDefinition[];
 	commands?: HubCommandDefinition[];
 	agents?: AgentDefinition[];
@@ -105,6 +111,7 @@ export interface InitMessage {
 	};
 	thinkingLevel?: string;
 	task?: string;
+	agentRole?: string;
 }
 
 export interface EventRequest {
@@ -159,10 +166,15 @@ export interface PingMessage {
 	timestamp: number;
 }
 
+export interface BootstrapReadyMessage {
+	type: 'bootstrap_ready';
+}
+
 export type HubClientMessage =
 	| HubRequest
 	| SessionEntryMessage
 	| SessionWriteMessage
+	| BootstrapReadyMessage
 	| RpcCommandMessage
 	| RpcUiResponseMessage
 	| PingMessage;
@@ -195,6 +207,14 @@ export interface ConnectionRejectedMessage {
 	timestamp: number;
 }
 
+export interface ProtocolErrorMessage {
+	type: 'protocol_error';
+	code: string;
+	message: string;
+	sessionId?: string;
+	timestamp: number;
+}
+
 export interface ConversationEntry {
 	type:
 		| 'message'
@@ -202,6 +222,9 @@ export interface ConversationEntry {
 		| 'tool_call'
 		| 'tool_result'
 		| 'task_result'
+		| 'runtime_status'
+		| 'runtime_output'
+		| 'runtime_preview'
 		| 'turn'
 		| 'user_prompt';
 	agent?: string;
@@ -210,6 +233,29 @@ export interface ConversationEntry {
 	toolName?: string;
 	toolArgs?: Record<string, unknown>;
 	toolCallId?: string;
+	runtime?:
+		| {
+				id?: string;
+				command?: string;
+				status?: string;
+				stream?: string;
+				exitCode?: number;
+		  }
+		| undefined;
+	preview?:
+		| {
+				id?: string;
+				url?: string;
+				status?: string;
+				label?: string;
+		  }
+		| undefined;
+	attachments?: Array<{
+		id?: string;
+		filename?: string;
+		mime?: string;
+		size?: number;
+	}>;
 	isError?: boolean;
 	taskId?: string;
 	turnId?: string;
@@ -219,16 +265,28 @@ export interface ConversationEntry {
 	timestamp: number;
 }
 
-export interface HydrationTaskState {
+export interface SessionTaskState {
 	taskId: string;
 	agent: string;
 	status: 'running' | 'completed' | 'failed';
 	prompt: string;
+	startedAt?: string;
+	completedAt?: string;
 	duration?: number;
 	result?: string;
 	error?: string;
 }
 
+export type HydrationTaskState = SessionTaskState;
+
+export interface SessionTaskProjection<TTaskState = SessionTaskState> {
+	tasks: TTaskState[];
+}
+
+export interface SessionStreamWorkExtension {
+	stream?: SessionStreamProjection;
+}
+
 export interface SessionParticipant {
 	id: string;
 	role: 'lead' | 'observer' | 'controller';
@@ -247,59 +305,252 @@ export interface SessionStreamProjection extends SessionStreamBlock {
 	tasks: Record<string, SessionStreamBlock>;
 }
 
-export interface SessionSnapshot {
+export type WorkflowMode = 'standard' | 'loop';
+export type LoopStatus =
+	| 'idle'
+	| 'starting'
+	| 'running'
+	| 'paused'
+	| 'awaiting_input'
+	| 'blocked'
+	| 'completed'
+	| 'failed'
+	| 'cancelled';
+
+export interface SessionLoopState {
+	workflowMode: WorkflowMode;
+	loopId?: string;
+	status: LoopStatus;
+	goal?: string;
+	summary?: string;
+	nextAction?: string;
+	blockers: string[];
+	iteration: number;
+	maxIterations: number;
+	autoContinue: boolean;
+	allowDetached: boolean;
+	recoveryAttempts: number;
+	awaitingUser: boolean;
+	activePrdKey?: string;
+	activePrdTaskId?: string;
+	coordinationJobId?: string;
+	currentWaveId?: string;
+	currentWaveLabel?: string;
+	lastCheckpointSummary?: string;
+	startedAt?: number;
+	updatedAt?: number;
+	lastCheckpointAt?: number;
+	completedAt?: number;
+	lastError?: string;
+}
+
+export type SessionBucket = 'running' | 'paused' | 'provisioning' | 'history';
+
+export interface SessionSkillRef {
+	skillId: string;
+	repo: string;
+	name?: string;
+	url?: string;
+}
+
+export interface SessionListDiagnostics {
+	inactiveRunningTasks: Array<{
+		taskId: string;
+		agent: string;
+		inactivityMs: number;
+		startedAt: string;
+		lastActivityAt?: string;
+	}>;
+}
+
+export interface SessionListItem {
 	sessionId: string;
 	label: string;
-	status: 'active' | 'paused' | 'shutdown' | 'archived' | 'error' | 'stopped';
+	status: string;
+	mode: 'sandbox' | 'tui';
+	sessionKind?: string;
+	parentSessionId?: string;
+	coordinationJobId?: string;
+	workflowMode: WorkflowMode;
+	loopStatus?: SessionLoopState['status'];
+	loopIteration?: number;
+	createdAt: string;
+	taskCount: number;
+	subAgentCount: number;
+	observerCount: number;
+	participantCount: number;
+	tags: string[];
+	skills: SessionSkillRef[];
+	defaultAgent?: string;
+	bucket: SessionBucket;
+	runtimeAvailable: boolean;
+	controlAvailable: boolean;
+	historyOnly: boolean;
+	diagnostics?: SessionListDiagnostics;
+}
+
+export interface SandboxSessionListItem {
+	sessionId: string;
+	sandboxId: string;
+	status: string;
+	task?: string;
+	metadata?: Record<string, unknown>;
+	wsConnected: boolean;
+}
+
+export interface SessionListResponse {
+	sessions: {
+		websocket: SessionListItem[];
+		sandbox: SandboxSessionListItem[];
+	};
+	total: number;
+}
+
+export interface SessionDetailParticipant {
+	id: string;
+	role: string;
+	transport: string;
+	connectedAt: string;
+	idle?: boolean;
+}
+
+export interface SessionAgentActivity {
+	name?: string;
+	status: string;
+	currentTool?: string;
+	currentToolArgs?: string;
+	toolCallCount: number;
+	lastActivity: number;
+	totalElapsed?: number;
+}
+
+export interface SessionObservedProjection {
+	turnCount: number;
+	lastAgentModel?: string;
+	compactionCount: number;
+}
+
+export interface SessionDeckGenerationState {
+	state: string;
+	requestedAt?: number;
+	startedAt?: number;
+	completedAt?: number;
+	title?: string;
+	deckType?: string;
+	prdKey?: string;
+	prdTaskId?: string;
+	todoId?: string;
+	error?: string;
+	url?: string;
+}
+
+export interface SessionProductProjection {
+	activePrdKey?: string;
+	activePrdTaskId?: string;
+	deckGeneration?: SessionDeckGenerationState;
+}
+
+export interface SessionActivityWorkExtensions {
+	agentActivity?: Record<string, SessionAgentActivity>;
+	diagnostics?: SessionListDiagnostics;
+}
+
+export interface SessionWorkProjection<TTaskState = SessionTaskState>
+	extends SessionTaskProjection<TTaskState>,
+		SessionStreamWorkExtension,
+		SessionActivityWorkExtensions {
+	workflowMode: WorkflowMode;
+}
+
+export interface SessionWorkflowProjection {
+	workflowMode: WorkflowMode;
+	loop?: SessionLoopState;
+}
+
+export interface SessionLoopResponse extends Omit<SessionWorkflowProjection, 'loop'> {
+	sessionId: string;
+	loop: SessionLoopState | null;
+}
+
+export interface SessionUsageAgentSummary {
+	inputTokens: number;
+	outputTokens: number;
+	reasoningTokens: number;
+	costUsd: number;
+	updatedAt: number;
+}
+
+export interface SessionUsageSummary {
+	inputTokens: number;
+	outputTokens: number;
+	reasoningTokens: number;
+	costUsd: number;
+	updatedAt: number;
+	byAgent?: Record<string, SessionUsageAgentSummary>;
+}
+
+export interface SessionSnapshotCore extends SessionTaskProjection {
+	sessionId: string;
+	label: string;
+	status: string;
 	createdAt: string;
 	mode: 'sandbox' | 'tui';
+	workflowMode: WorkflowMode;
+	participants: SessionDetailParticipant[];
 	task?: string;
 	error?: string;
-	streamId?: string | null;
-	streamUrl?: string | null;
+	bucket: SessionBucket;
+	runtimeAvailable: boolean;
+	controlAvailable: boolean;
+	historyOnly: boolean;
+}
+
+export interface SessionSnapshotHistoryExtensions {
+	streamId: string | null;
+	streamUrl: string | null;
+}
+
+export interface SessionSnapshotWorkExtensions
+	extends SessionStreamWorkExtension,
+		SessionActivityWorkExtensions {
+	agentActivity: Record<string, SessionAgentActivity>;
+	usage: SessionUsageSummary;
+}
+
+export interface SessionSnapshotWorkflowExtensions
+	extends Pick<SessionWorkflowProjection, 'loop'> {}
+
+export interface SessionSnapshotMetadataExtensions {
 	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[];
+	observed?: SessionObservedProjection;
+	product?: SessionProductProjection;
+	tags: string[];
+	skills: SessionSkillRef[];
 	defaultAgent?: string;
-	bucket?: 'running' | 'paused' | 'provisioning' | 'history';
-	runtimeAvailable?: boolean;
-	controlAvailable?: boolean;
-	historyOnly?: boolean;
+	workers?: SessionListItem[];
 }
 
-export interface CoderHubHydrationMessage {
+export interface SessionSnapshotExtensions
+	extends SessionSnapshotHistoryExtensions,
+		SessionSnapshotWorkExtensions,
+		SessionSnapshotWorkflowExtensions,
+		SessionSnapshotMetadataExtensions {}
+
+export interface SessionSnapshot extends SessionSnapshotCore, SessionSnapshotExtensions {}
+
+export interface CoderHubHydrationMessage
+	extends SessionTaskProjection<HydrationTaskState>,
+		SessionStreamWorkExtension {
 	type: 'session_hydration';
 	sessionId: string;
+	label?: string;
 	resumedAt: number;
 	entries: ConversationEntry[];
-	tasks: HydrationTaskState[];
-	stream?: SessionStreamProjection;
 	task?: string;
+	leadConnected?: boolean;
 	streamingState?: {
 		isStreaming?: boolean;
 		activeTasks?: Array<{
@@ -327,6 +578,133 @@ export interface BroadcastEventMessage {
 	timestamp?: number;
 }
 
+export type ReplayEntry = ConversationEntry;
+
+export interface ReplayHistoryResponse {
+	sessionId: string;
+	entriesSource: 'durable_stream' | 'session_entries' | 'event_history' | 'none';
+	sourceCounts?: {
+		durableStream: number;
+		sessionEntries: number;
+		eventHistory: number;
+	};
+	entries: ReplayEntry[];
+}
+
+export interface SessionEventHistoryItem {
+	id: number;
+	event: string;
+	category: string;
+	agent?: string;
+	taskId?: string;
+	payload: Record<string, unknown>;
+	occurredAt: string;
+	ingestedAt: string;
+}
+
+export interface SessionEventHistoryResponse {
+	sessionId: string;
+	events: SessionEventHistoryItem[];
+}
+
+export interface SessionParticipantHistoryItem {
+	id: string;
+	role: string;
+	transport: string;
+	agentRole?: string;
+	connectedAt: string;
+	disconnectedAt?: string;
+	lastActivityAt: string;
+	metadata?: Record<string, unknown>;
+}
+
+export interface SessionParticipantsResponse {
+	sessionId: string;
+	participants: SessionParticipantHistoryItem[];
+}
+
+export interface SessionTodoSummary {
+	open: number;
+	in_progress: number;
+	done: number;
+	closed: number;
+	cancelled: number;
+}
+
+export interface SessionTodoAssignee {
+	id: string;
+	name: string;
+	type?: string;
+}
+
+export interface SessionTodoItem {
+	id: string;
+	title: string;
+	status: 'open' | 'in_progress' | 'done' | 'closed' | 'cancelled';
+	type?: string | null;
+	priority?: string | null;
+	parentTaskId?: string | null;
+	prdKey?: string | null;
+	externalRef?: string | null;
+	taskKey?: string | null;
+	origin?: string | null;
+	kind?: string | null;
+	assignee?: SessionTodoAssignee | null;
+	lastSessionId?: string | null;
+	sessionIds: string[];
+	tags: string[];
+	memoryKeys: string[];
+	memoryIds: string[];
+	touchedByAgents: string[];
+	lastTouchedByAgent?: string | null;
+	attachments: Array<Record<string, unknown>>;
+	attachmentCount: number;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface SessionTodoListResponse {
+	sessionId: string;
+	ok: boolean;
+	op: 'session_todo_list';
+	count: number;
+	summary: SessionTodoSummary;
+	todos: SessionTodoItem[];
+	unavailable?: boolean;
+	message?: string;
+}
+
+export type SseSessionSnapshotParticipant = SessionDetailParticipant;
+
+export interface SseHydrationTaskState {
+	taskId: string;
+	agent: string;
+	status: SessionTaskState['status'];
+	prompt: string;
+}
+
+export interface SseSessionSnapshotMessage {
+	type: 'snapshot';
+	sessionId: string;
+	label: string;
+	status: string;
+	createdAt: string;
+	mode: 'sandbox' | 'tui';
+	participants: SseSessionSnapshotParticipant[];
+	taskCount: number;
+	agentActivity: Record<string, SessionAgentActivity>;
+	stream?: SessionStreamProjection;
+}
+
+export interface SseHydrationMessage
+	extends SessionTaskProjection<SseHydrationTaskState>,
+		SessionStreamWorkExtension {
+	type: 'hydration';
+	sessionId: string;
+	entries: ConversationEntry[];
+	task?: string;
+}
+
 export interface RpcEventMessage {
 	type: 'rpc_event';
 	event: Record<string, unknown>;
@@ -352,6 +730,9 @@ export type ServerMessage =
 	| CoderHubStreamReadyMessage
 	| CoderHubSessionResumeMessage
 	| ConnectionRejectedMessage
+	| ProtocolErrorMessage
+	| SseSessionSnapshotMessage
+	| SseHydrationMessage
 	| PresenceEventMessage
 	| BroadcastEventMessage
 	| RpcEventMessage

package/src/remote-session.ts

@@ -265,11 +265,6 @@ export class RemoteSession {
 
 			this.ws.onopen = () => {
 				log('WebSocket connected');
-				try {
-					this.ws?.send(JSON.stringify({ type: 'controller_ready' }));
-				} catch {
-					// Let the normal init timeout surface if bootstrap cannot start.
-				}
 			};
 
 			this.ws.onmessage = (event: MessageEvent) => {
@@ -292,11 +287,17 @@ export class RemoteSession {
 					this.connected = true;
 					this.reconnectAttempts = 0;
 					if (data.sessionId) this.sessionId = data.sessionId as string;
+					if (typeof data.label === 'string') this.label = data.label;
 					this.applyLifecycle({
 						type: 'init',
 						sessionId: typeof data.sessionId === 'string' ? data.sessionId : undefined,
 						label: typeof data.label === 'string' ? data.label : undefined,
 					});
+					try {
+						this.ws?.send(JSON.stringify({ type: 'bootstrap_ready' }));
+					} catch {
+						// Let the close/error path surface bootstrap failure.
+					}
 					log(`Connected to session ${this.sessionId}`);
 					this.notifyConnectionChange('connected');
 					resolve();
@@ -316,6 +317,25 @@ export class RemoteSession {
 					return;
 				}
 
+				if (type === 'protocol_error') {
+					clearTimeout(connectTimeout);
+					const msg = (data.message as string) || 'Hub protocol error';
+					this.applyLifecycle({
+						type: 'rpc_command_error',
+						error: msg,
+						paused: false,
+					});
+					this.dispatchEvent({
+						type: 'protocol_error',
+						...data,
+						_source: 'hub',
+					} as RpcEvent);
+					if (!this.connected) {
+						reject(new Error(msg));
+					}
+					return;
+				}
+
 				if (type === 'session_resume') {
 					this.applyLifecycle({
 						type: 'session_resume',
@@ -405,7 +425,7 @@ export class RemoteSession {
 					return;
 				}
 
-				// Raw RPC messages (from Durable Stream replay — historical, not live)
+				// Legacy/raw RPC messages — tolerated but not expected on the controller path.
 				if (type === 'rpc_event') {
 					const rpcEvent = data.event as RpcEvent;
 					if (rpcEvent) {