@nextclaw/ui 0.10.1 → 0.10.3

package/src/App.test.tsx

@@ -0,0 +1,59 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import AppContent from '@/App';
+
+const mocks = vi.hoisted(() => ({
+  refetch: vi.fn(),
+  useAuthStatus: vi.fn()
+}));
+
+vi.mock('@/hooks/use-auth', () => ({
+  useAuthStatus: mocks.useAuthStatus
+}));
+
+describe('App auth bootstrap', () => {
+  beforeEach(() => {
+    mocks.refetch.mockReset();
+    mocks.useAuthStatus.mockReset();
+  });
+
+  it('shows an actionable error state instead of staying blank when auth bootstrap fails', async () => {
+    const user = userEvent.setup();
+    mocks.useAuthStatus.mockReturnValue({
+      isLoading: false,
+      isError: true,
+      isRefetching: false,
+      error: new Error('Timed out waiting for remote request response after 5000ms: GET /api/auth/status'),
+      refetch: mocks.refetch,
+      data: undefined
+    });
+
+    render(<AppContent />);
+
+    expect(screen.getByRole('heading', { name: /load authentication status/i })).toBeTruthy();
+    expect(screen.getByText('Timed out waiting for remote request response after 5000ms: GET /api/auth/status')).toBeTruthy();
+
+    await user.click(screen.getByRole('button', { name: /retry/i }));
+
+    expect(mocks.refetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows a startup state while the local UI service is still booting', () => {
+    mocks.useAuthStatus.mockReturnValue({
+      isLoading: true,
+      isError: false,
+      isRefetching: false,
+      failureCount: 1,
+      failureReason: new Error('Failed to fetch'),
+      error: null,
+      refetch: mocks.refetch,
+      data: undefined
+    });
+
+    render(<AppContent />);
+
+    expect(screen.getByRole('heading', { name: /waiting for the local ui service to start/i })).toBeTruthy();
+    expect(screen.getByText('Failed to fetch')).toBeTruthy();
+  });
+});

package/src/App.tsx

@@ -3,8 +3,10 @@ import { QueryClientProvider } from '@tanstack/react-query';
 import { AccountPanel } from '@/account/components/account-panel';
 import { appQueryClient } from '@/app-query-client';
 import { LoginPage } from '@/components/auth/login-page';
+import { Button } from '@/components/ui/button';
 import { AppLayout } from '@/components/layout/AppLayout';
 import { useAuthStatus } from '@/hooks/use-auth';
+import { t } from '@/lib/i18n';
 import { useRealtimeQueryBridge } from '@/hooks/use-realtime-query-bridge';
 import { AppPresenterProvider } from '@/presenter/app-presenter-context';
 import { Toaster } from 'sonner';
@@ -31,6 +33,46 @@ function LazyRoute({ children }: { children: JSX.Element }) {
   return <Suspense fallback={<RouteFallback />}>{children}</Suspense>;
 }
 
+function AuthBootstrapErrorState(props: {
+  message: string;
+  retrying: boolean;
+  onRetry: () => void;
+}) {
+  return (
+    <main className="flex min-h-screen items-center justify-center bg-secondary px-6 py-10">
+      <div className="w-full max-w-lg rounded-3xl border border-gray-200 bg-white p-8 shadow-card">
+        <p className="text-xs font-semibold uppercase tracking-[0.24em] text-gray-500">{t('authBrand')}</p>
+        <h1 className="mt-3 text-2xl font-semibold text-gray-900">{t('authStatusLoadFailed')}</h1>
+        <p className="mt-3 text-sm leading-6 text-gray-600">
+          {props.message}
+        </p>
+        <div className="mt-6 flex gap-3">
+          <Button onClick={props.onRetry} disabled={props.retrying}>
+            {t('authRetryStatus')}
+          </Button>
+        </div>
+      </div>
+    </main>
+  );
+}
+
+function AuthBootstrapLoadingState(props: { message?: string }) {
+  return (
+    <main className="flex min-h-screen items-center justify-center bg-secondary px-6 py-10">
+      <div className="w-full max-w-lg rounded-3xl border border-gray-200 bg-white p-8 shadow-card">
+        <p className="text-xs font-semibold uppercase tracking-[0.24em] text-gray-500">{t('authBrand')}</p>
+        <h1 className="mt-3 text-2xl font-semibold text-gray-900">{t('authStatusStarting')}</h1>
+        <p className="mt-3 text-sm leading-6 text-gray-600">{t('authStatusStartingHint')}</p>
+        {props.message ? (
+          <p className="mt-4 rounded-2xl border border-dashed border-gray-200 bg-gray-50 px-4 py-3 text-xs leading-5 text-gray-500">
+            {props.message}
+          </p>
+        ) : null}
+      </div>
+    </main>
+  );
+}
+
 function ProtectedApp() {
   useRealtimeQueryBridge(appQueryClient);
 
@@ -72,7 +114,23 @@ function AuthGate() {
   const authStatus = useAuthStatus();
 
   if (authStatus.isLoading && !authStatus.isError) {
-    return <RouteFallback />;
+    const failureMessage =
+      authStatus.failureCount > 0 && authStatus.failureReason instanceof Error
+        ? authStatus.failureReason.message
+        : undefined;
+    return <AuthBootstrapLoadingState message={failureMessage} />;
+  }
+
+  if (authStatus.isError) {
+    return (
+      <AuthBootstrapErrorState
+        message={authStatus.error instanceof Error ? authStatus.error.message : t('authStatusLoadFailed')}
+        retrying={authStatus.isRefetching}
+        onRetry={() => {
+          void authStatus.refetch();
+        }}
+      />
+    );
   }
 
   if (authStatus.data?.enabled && !authStatus.data.authenticated) {

package/src/api/client.test.ts

@@ -30,6 +30,18 @@ describe('api/client', () => {
     });
   });
 
+  it('forwards timeout overrides to appClient.request', async () => {
+    mocks.request.mockResolvedValue({ ok: true });
+
+    await api.get<{ ok: boolean }>('/api/auth/status', { timeoutMs: 5000 });
+
+    expect(mocks.request).toHaveBeenCalledWith({
+      method: 'GET',
+      path: '/api/auth/status',
+      timeoutMs: 5000
+    });
+  });
+
   it('parses JSON request bodies before sending to appClient.request', async () => {
     mocks.request.mockResolvedValue({ success: true });
 

package/src/api/client.ts

@@ -3,13 +3,14 @@ import type { ApiResponse } from './types';
 
 export async function requestApiResponse<T>(
   endpoint: string,
-  options: RequestInit = {}
+  options: RequestInit & { timeoutMs?: number } = {}
 ): Promise<ApiResponse<T>> {
   const method = (options.method || 'GET').toUpperCase();
   try {
     const data = await appClient.request<T>({
       method: method as 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
       path: endpoint,
+      ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
       ...(options.body !== undefined ? { body: parseRequestBody(options.body) } : {})
     });
     return {
@@ -32,7 +33,8 @@ export async function requestApiResponse<T>(
 }
 
 export const api = {
-  get: <T>(path: string) => requestApiResponse<T>(path, { method: 'GET' }),
+  get: <T>(path: string, options: RequestInit & { timeoutMs?: number } = {}) =>
+    requestApiResponse<T>(path, { ...options, method: 'GET' }),
   put: <T>(path: string, body: unknown) =>
     requestApiResponse<T>(path, {
       method: 'PUT',

package/src/api/config.ts

@@ -54,7 +54,7 @@ import type {
 
 // GET /api/auth/status
 export async function fetchAuthStatus(): Promise<AuthStatusView> {
-  const response = await api.get<AuthStatusView>('/api/auth/status');
+  const response = await api.get<AuthStatusView>('/api/auth/status', { timeoutMs: 5_000 });
   if (!response.ok) {
     throw new Error(response.error.message);
   }

package/src/components/chat/chat-composer-state.test.ts

@@ -0,0 +1,74 @@
+import { createChatComposerTextNode, createChatComposerTokenNode } from '@nextclaw/agent-chat-ui';
+import { deriveNcpMessagePartsFromComposer } from '@/components/chat/chat-composer-state';
+
+describe('deriveNcpMessagePartsFromComposer', () => {
+  it('preserves interleaved text and image token order while skipping skill tokens', () => {
+    const parts = deriveNcpMessagePartsFromComposer(
+      [
+        createChatComposerTextNode('before '),
+        createChatComposerTokenNode({
+          tokenKind: 'file',
+          tokenKey: 'image-1',
+          label: 'one.png'
+        }),
+        createChatComposerTextNode(' between '),
+        createChatComposerTokenNode({
+          tokenKind: 'skill',
+          tokenKey: 'web-search',
+          label: 'Web Search'
+        }),
+        createChatComposerTextNode('after'),
+        createChatComposerTokenNode({
+          tokenKind: 'file',
+          tokenKey: 'image-2',
+          label: 'two.png'
+        })
+      ],
+      [
+        {
+          id: 'image-1',
+          name: 'one.png',
+          mimeType: 'image/png',
+          contentBase64: 'aW1hZ2UtMQ==',
+          sizeBytes: 10
+        },
+        {
+          id: 'image-2',
+          name: 'two.png',
+          mimeType: 'image/png',
+          contentBase64: 'aW1hZ2UtMg==',
+          sizeBytes: 12
+        }
+      ]
+    );
+
+    expect(parts).toEqual([
+      {
+        type: 'text',
+        text: 'before '
+      },
+      {
+        type: 'file',
+        name: 'one.png',
+        mimeType: 'image/png',
+        contentBase64: 'aW1hZ2UtMQ==',
+        sizeBytes: 10
+      },
+      {
+        type: 'text',
+        text: ' between '
+      },
+      {
+        type: 'text',
+        text: 'after'
+      },
+      {
+        type: 'file',
+        name: 'two.png',
+        mimeType: 'image/png',
+        contentBase64: 'aW1hZ2UtMg==',
+        sizeBytes: 12
+      }
+    ]);
+  });
+});

package/src/components/chat/chat-composer-state.ts

@@ -1,4 +1,5 @@
 import type { ChatComposerNode } from '@nextclaw/agent-chat-ui';
+import type { NcpMessagePart } from '@nextclaw/ncp';
 import type { NcpDraftAttachment } from '@nextclaw/ncp-react';
 import {
   createChatComposerTokenNode,
@@ -62,24 +63,10 @@ export function syncComposerAttachments(
   attachments: readonly NcpDraftAttachment[]
 ): ChatComposerNode[] {
   const nextAttachmentIds = new Set(attachments.map((attachment) => attachment.id));
-  const prunedNodes = removeChatComposerTokenNodes(
+  return removeChatComposerTokenNodes(
     nodes,
     (node) => node.tokenKind === 'file' && !nextAttachmentIds.has(node.tokenKey)
   );
-  const existingAttachmentIds = extractChatComposerTokenKeys(prunedNodes, 'file');
-  const appendedNodes = attachments
-    .filter((attachment) => !existingAttachmentIds.includes(attachment.id))
-    .map((attachment) =>
-      createChatComposerTokenNode({
-        tokenKind: 'file',
-        tokenKey: attachment.id,
-        label: attachment.name
-      })
-    );
-
-  return appendedNodes.length === 0
-    ? prunedNodes
-    : normalizeChatComposerNodes([...prunedNodes, ...appendedNodes]);
 }
 
 export function pruneComposerAttachments(
@@ -89,3 +76,42 @@ export function pruneComposerAttachments(
   const selectedIds = new Set(deriveSelectedAttachmentIdsFromComposer(nodes));
   return attachments.filter((attachment) => selectedIds.has(attachment.id));
 }
+
+export function deriveNcpMessagePartsFromComposer(
+  nodes: ChatComposerNode[],
+  attachments: readonly NcpDraftAttachment[]
+): NcpMessagePart[] {
+  const attachmentById = new Map(attachments.map((attachment) => [attachment.id, attachment]));
+  const parts: NcpMessagePart[] = [];
+
+  for (const node of nodes) {
+    if (node.type === 'text') {
+      if (node.text.length > 0) {
+        parts.push({
+          type: 'text',
+          text: node.text
+        });
+      }
+      continue;
+    }
+
+    if (node.tokenKind !== 'file') {
+      continue;
+    }
+
+    const attachment = attachmentById.get(node.tokenKey);
+    if (!attachment) {
+      continue;
+    }
+
+    parts.push({
+      type: 'file',
+      name: attachment.name,
+      mimeType: attachment.mimeType,
+      contentBase64: attachment.contentBase64,
+      sizeBytes: attachment.sizeBytes
+    });
+  }
+
+  return parts;
+}

package/src/components/chat/chat-stream/types.ts

@@ -1,4 +1,5 @@
 import type { ChatComposerNode } from '@nextclaw/agent-chat-ui';
+import type { NcpMessagePart } from '@nextclaw/ncp';
 import type { NcpDraftAttachment } from '@nextclaw/ncp-react';
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
 import type {
@@ -20,6 +21,7 @@ export type SendMessageParams = {
   thinkingLevel?: ThinkingLevel;
   requestedSkills?: string[];
   attachments?: NcpDraftAttachment[];
+  parts?: NcpMessagePart[];
   stopSupported?: boolean;
   stopReason?: string;
   restoreDraftOnError?: boolean;

package/src/components/chat/containers/chat-input-bar.container.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useMemo, useRef, useState } from 'react';
-import { ChatInputBar } from '@nextclaw/agent-chat-ui';
+import { ChatInputBar, type ChatInputBarHandle } from '@nextclaw/agent-chat-ui';
 import {
   DEFAULT_NCP_IMAGE_ATTACHMENT_ACCEPT,
   DEFAULT_NCP_IMAGE_ATTACHMENT_MAX_BYTES,
@@ -76,6 +76,7 @@ export function ChatInputBarContainer() {
   const { language } = useI18n();
   const snapshot = useChatInputStore((state) => state.snapshot);
   const [slashQuery, setSlashQuery] = useState<string | null>(null);
+  const inputBarRef = useRef<ChatInputBarHandle | null>(null);
   const fileInputRef = useRef<HTMLInputElement | null>(null);
 
   const officialSkillBadgeLabel = useMemo(() => {
@@ -150,7 +151,15 @@ export function ChatInputBarContainer() {
     }
     const result = await readFilesAsNcpDraftAttachments(files);
     if (result.attachments.length > 0) {
-      presenter.chatInputManager.addAttachments?.(result.attachments);
+      const insertedAttachments = presenter.chatInputManager.addAttachments?.(result.attachments) ?? [];
+      if (insertedAttachments.length > 0) {
+        inputBarRef.current?.insertFileTokens(
+          insertedAttachments.map((attachment) => ({
+            tokenKey: attachment.id,
+            label: attachment.name
+          }))
+        );
+      }
     }
     if (result.rejected.length > 0) {
       showAttachmentError(result.rejected[0].reason);
@@ -197,6 +206,7 @@ export function ChatInputBarContainer() {
   return (
     <>
       <ChatInputBar
+        ref={inputBarRef}
         composer={{
           nodes: snapshot.composerNodes,
           placeholder: textareaPlaceholder,

package/src/components/chat/ncp/NcpChatPage.tsx

@@ -194,6 +194,7 @@ export function NcpChatPage({ view }: ChatPageProps) {
           sessionId: payload.sessionKey,
           text: payload.message,
           attachments: payload.attachments,
+          parts: payload.parts,
           metadata
         });
         if (!envelope) {

package/src/components/chat/ncp/ncp-chat-input.manager.ts

@@ -7,6 +7,7 @@ import {
   createChatComposerNodesFromDraft,
   createInitialChatComposerNodes,
   deriveChatComposerDraft,
+  deriveNcpMessagePartsFromComposer,
   deriveSelectedSkillsFromComposer,
   pruneComposerAttachments,
   syncComposerAttachments,
@@ -24,6 +25,14 @@ import { normalizeSessionType } from '@/components/chat/useChatSessionTypeState'
 export class NcpChatInputManager {
   private readonly sessionPreferenceSync = new ChatSessionPreferenceSync(updateNcpSession);
 
+  private buildAttachmentSignature = (attachment: NcpDraftAttachment): string =>
+    [
+      attachment.name,
+      attachment.mimeType,
+      String(attachment.sizeBytes),
+      attachment.contentBase64,
+    ].join(':');
+
   constructor(
     private uiManager: ChatUiManager,
     private streamActionsManager: ChatStreamActionsManager,
@@ -77,12 +86,7 @@ export class NcpChatInputManager {
     const seen = new Set<string>();
     const output: NcpDraftAttachment[] = [];
     for (const attachment of attachments) {
-      const signature = [
-        attachment.name,
-        attachment.mimeType,
-        String(attachment.sizeBytes),
-        attachment.contentBase64,
-      ].join(':');
+      const signature = this.buildAttachmentSignature(attachment);
       if (seen.has(signature)) {
         continue;
       }
@@ -125,14 +129,22 @@ export class NcpChatInputManager {
     this.syncComposerSnapshot(value);
   };
 
-  addAttachments = (attachments: NcpDraftAttachment[]) => {
+  addAttachments = (attachments: NcpDraftAttachment[]): NcpDraftAttachment[] => {
     if (attachments.length === 0) {
-      return;
+      return [];
     }
     const snapshot = useChatInputStore.getState().snapshot;
+    const existingSignatures = new Set(snapshot.attachments.map(this.buildAttachmentSignature));
     const nextAttachments = this.dedupeAttachments([...snapshot.attachments, ...attachments]);
+    const insertedAttachments = nextAttachments.filter(
+      (attachment) => !existingSignatures.has(this.buildAttachmentSignature(attachment))
+    );
+    if (insertedAttachments.length === 0) {
+      return [];
+    }
     const nextNodes = syncComposerAttachments(snapshot.composerNodes, nextAttachments);
     this.syncComposerSnapshotWithAttachments(nextNodes, nextAttachments);
+    return insertedAttachments;
   };
 
   restoreComposerState = (nodes: ChatComposerNode[], attachments: NcpDraftAttachment[]) => {
@@ -155,7 +167,11 @@ export class NcpChatInputManager {
     const sessionSnapshot = useChatSessionListStore.getState().snapshot;
     const message = inputSnapshot.draft.trim();
     const attachments = inputSnapshot.attachments;
-    if (!message && attachments.length === 0) {
+    const parts = deriveNcpMessagePartsFromComposer(inputSnapshot.composerNodes, attachments);
+    const hasSendableContent = parts.some(
+      (part) => part.type !== 'text' || part.text.trim().length > 0
+    );
+    if (!hasSendableContent) {
       return;
     }
     const { selectedSkills: requestedSkills, composerNodes } = inputSnapshot;
@@ -174,6 +190,7 @@ export class NcpChatInputManager {
       stopSupported: true,
       requestedSkills,
       attachments,
+      parts,
       restoreDraftOnError: true,
       composerNodes
     });

package/src/components/chat/ncp/ncp-session-adapter.test.ts

@@ -1,4 +1,5 @@
 import {
+  adaptNcpMessageToUiMessage,
   adaptNcpSessionSummary,
   buildNcpSessionRunStatusByKey,
   readNcpSessionPreferredThinking
@@ -40,6 +41,45 @@ describe('adaptNcpSessionSummary', () => {
   });
 });
 
+describe('adaptNcpMessageToUiMessage', () => {
+  it('preserves mixed text and image part order for message rendering', () => {
+    const adapted = adaptNcpMessageToUiMessage({
+      id: 'ncp-message-1',
+      sessionId: 'ncp-session-1',
+      role: 'user',
+      status: 'final',
+      timestamp: '2026-03-25T00:00:00.000Z',
+      parts: [
+        { type: 'text', text: 'before ' },
+        {
+          type: 'file',
+          name: 'sample.png',
+          mimeType: 'image/png',
+          contentBase64: 'ZmFrZS1pbWFnZQ==',
+          sizeBytes: 10
+        },
+        { type: 'text', text: ' after' }
+      ]
+    });
+
+    expect(adapted.parts).toEqual([
+      {
+        type: 'text',
+        text: 'before '
+      },
+      {
+        type: 'file',
+        mimeType: 'image/png',
+        data: 'ZmFrZS1pbWFnZQ=='
+      },
+      {
+        type: 'text',
+        text: ' after'
+      }
+    ]);
+  });
+});
+
 describe('readNcpSessionPreferredThinking', () => {
   it('normalizes persisted thinking metadata for UI hydration', () => {
     const thinking = readNcpSessionPreferredThinking(

package/src/components/chat/presenter/chat-presenter-context.tsx

@@ -14,7 +14,7 @@ export type ChatInputManagerLike = {
   syncSnapshot: (patch: Record<string, unknown>) => void;
   setDraft: (next: SetStateAction<string>) => void;
   setComposerNodes: (next: SetStateAction<ChatComposerNode[]>) => void;
-  addAttachments?: (attachments: NcpDraftAttachment[]) => void;
+  addAttachments?: (attachments: NcpDraftAttachment[]) => NcpDraftAttachment[];
   restoreComposerState?: (
     nodes: ChatComposerNode[],
     attachments: NcpDraftAttachment[]

package/src/hooks/use-auth.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { isRetryableAuthBootstrapError } from '@/hooks/use-auth';
+
+describe('isRetryableAuthBootstrapError', () => {
+  it('treats transient bootstrap fetch failures as retryable', () => {
+    expect(isRetryableAuthBootstrapError(new Error('Failed to fetch'))).toBe(true);
+    expect(isRetryableAuthBootstrapError(new Error('Timed out waiting for remote request response after 5000ms'))).toBe(true);
+    expect(isRetryableAuthBootstrapError(new Error('connect ECONNREFUSED 127.0.0.1:18792'))).toBe(true);
+  });
+
+  it('does not retry non-error values or permanent failures', () => {
+    expect(isRetryableAuthBootstrapError('Failed to fetch')).toBe(false);
+    expect(isRetryableAuthBootstrapError(new Error('Authentication required.'))).toBe(false);
+  });
+});

package/src/hooks/use-auth.ts

@@ -10,13 +10,33 @@ import {
 import { toast } from 'sonner';
 import { t } from '@/lib/i18n';
 
+const AUTH_BOOTSTRAP_RETRY_DELAYS_MS = [1000, 1500, 2000, 3000, 4000] as const;
+
+export function isRetryableAuthBootstrapError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const message = error.message.trim().toLowerCase();
+  return (
+    message.includes('failed to fetch') ||
+    message.includes('networkerror') ||
+    message.includes('network request failed') ||
+    message.includes('load failed') ||
+    message.includes('timed out') ||
+    message.includes('econnrefused') ||
+    message.includes('socket hang up')
+  );
+}
+
 export function useAuthStatus() {
   return useQuery({
     queryKey: ['auth-status'],
     queryFn: fetchAuthStatus,
     staleTime: 5_000,
-    retry: 3,
-    retryDelay: (attempt) => Math.min(1000 * attempt, 3000),
+    retry: (failureCount, error) =>
+      failureCount < AUTH_BOOTSTRAP_RETRY_DELAYS_MS.length && isRetryableAuthBootstrapError(error),
+    retryDelay: (attemptIndex) => AUTH_BOOTSTRAP_RETRY_DELAYS_MS[Math.min(attemptIndex, AUTH_BOOTSTRAP_RETRY_DELAYS_MS.length - 1)],
     refetchOnWindowFocus: true
   });
 }

package/src/lib/i18n.ts

@@ -390,6 +390,8 @@ export const LABELS: Record<string, { zh: string; en: string }> = {
   authDisabledSuccess: { zh: '认证已关闭', en: 'Authentication disabled' },
   authRetryStatus: { zh: '重试', en: 'Retry' },
   authStatusLoadFailed: { zh: '无法获取认证状态，请检查 UI 服务是否正常。', en: 'Failed to load authentication status. Check whether the UI server is healthy.' },
+  authStatusStarting: { zh: '正在等待本地 UI 服务启动...', en: 'Waiting for the local UI service to start...' },
+  authStatusStartingHint: { zh: '开发环境冷启动时，后端可能还在初始化插件、渠道和 MCP 服务。', en: 'During a cold dev start, the backend may still be initializing plugins, channels, and MCP services.' },
 
   // Runtime
   runtimePageTitle: { zh: '路由与运行时', en: 'Routing & Runtime' },

package/src/transport/local.transport.ts

@@ -114,14 +114,35 @@ export class LocalAppTransport implements AppTransport {
   }
 
   async request<T>(input: RequestInput): Promise<T> {
-    const response = await requestRawApiResponse<T>(input.path, {
-      method: input.method,
-      ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {})
-    });
-    if (!response.ok) {
-      throw createTransportError(response, `Request failed for ${input.method} ${input.path}`);
+    const timeoutMs = Number.isFinite(input.timeoutMs) && (input.timeoutMs ?? 0) > 0
+      ? Math.trunc(input.timeoutMs as number)
+      : null;
+    const controller = timeoutMs ? new AbortController() : null;
+    const timeoutId = timeoutMs
+      ? window.setTimeout(() => controller?.abort(`Request timed out after ${timeoutMs}ms: ${input.method} ${input.path}`), timeoutMs)
+      : null;
+
+    try {
+      const response = await requestRawApiResponse<T>(input.path, {
+        method: input.method,
+        ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
+        ...(controller ? { signal: controller.signal } : {})
+      });
+      if (!response.ok) {
+        throw createTransportError(response, `Request failed for ${input.method} ${input.path}`);
+      }
+      return response.data;
+    } catch (error) {
+      if (controller?.signal.aborted) {
+        const reason = controller.signal.reason;
+        throw new Error(typeof reason === 'string' && reason.trim() ? reason : `Request timed out: ${input.method} ${input.path}`);
+      }
+      throw error;
+    } finally {
+      if (timeoutId !== null) {
+        window.clearTimeout(timeoutId);
+      }
     }
-    return response.data;
   }
 
   openStream<TFinal = unknown>(input: StreamInput): StreamSession<TFinal> {

package/src/transport/remote.transport.test.ts

@@ -117,7 +117,7 @@ describe('RemoteSessionMultiplexTransport request path', () => {
       path: '/api/sessions'
     });
     const timeoutExpectation = expect(requestPromise).rejects.toThrow(
-      'Timed out waiting for remote request response: GET /api/sessions'
+      'Timed out waiting for remote request response after 15000ms: GET /api/sessions'
     );
 
     const socket = MockWebSocket.instances[0];