feat(desktop): show context usage beside the model controls

A read-only indicator in the composer's model controls shows the latest
request as the provider counted it: input plus output tokens of the last
accepted request, read from the session's newest token_usage record. With
a user-declared Maka window it shows the percentage (over 100% is shown as
such, never clamped); without one it shows the absolute count and names the
model's reported window in a tooltip; without usage it shows a dash and
says the provider reported none. Chat model choices carry the reported and
the declared window separately so the two are never confused (#4559).

Refs #4559

Generated-by: Claude Code
Claude-Session: https://claude.ai/code/session_014ajaRxC4jydavY9nYUFj5J

Author: Joob1n

apps/desktop/renderer-architecture.json

@@ -791,7 +791,7 @@
         "nonTriviaTokens": 1425
       },
       "src/renderer/app-shell.tsx": {
-        "importDeclarations": 105,
+        "importDeclarations": 104,
         "bridgePaths": {
           "window.maka.app.installUpdate": 1,
           "window.maka.app.retryUpdateDownload": 1,
@@ -975,7 +975,7 @@
           "@maka/core/onboarding-milestone": 1,
           "@maka/core/orchestration": 1,
           "@maka/core/project": 1,
-          "@maka/core/session": 2,
+          "@maka/core/session": 1,
           "@maka/core/session-revisions": 1,
           "@maka/core/settings": 1,
           "@maka/core/slash-command-catalog": 2,
@@ -984,8 +984,8 @@
           "@maka/ui/icons": 1,
           "react": 1
         },
-        "importSpecifiers": 186,
-        "nonTriviaTokens": 15725
+        "importSpecifiers": 185,
+        "nonTriviaTokens": 15715
       },
       "src/renderer/use-app-shell-composer-quotes.ts": {
         "importDeclarations": 3,

apps/desktop/src/main/__tests__/chat-composer-region-draft-handoff.test.ts

@@ -113,6 +113,7 @@ async function mountRegion(): Promise<{
               composerRef: composer,
               directoryComposerProps: {},
               directoryPickerEnabled: false,
+              messages: [],
               active: true,
               onboardingComposerHidden: false,
               activeInteraction: undefined,

apps/desktop/src/renderer/app-shell.tsx

@@ -35,7 +35,6 @@ import type {
   InlineReference,
   QuoteRef,
 } from '@maka/core/events';
-import type { SessionSummary } from '@maka/core/session';
 import type { OrchestrationMode } from '@maka/core/orchestration';
 import type { ChatDefaultPermissionMode } from '@maka/core/settings';
 import type { SlashCommandIdForSurface } from '@maka/core/slash-command-catalog';
@@ -955,10 +954,9 @@ function AppShellContent({
     openModelPicker: openComposerModelPicker,
     refreshModelChoices: sessionHostConnections.refreshConnections,
   });
-  const newChatProviderType = newChatModel
-    ? connections.find((connection) => connection.slug === newChatModel.llmConnectionSlug)?.providerType
-    : undefined;
-
+  const newChatProviderType = connections.find(
+    (connection) => connection.slug === newChatModel?.llmConnectionSlug,
+  )?.providerType;
   // PR109d-b: turn footer actions per turn. Derived from the
   // materialized turn list (status + lineage descendants) + pending
   // mask. Per @kenji PR109d review: pending state prevents double-click
@@ -1167,15 +1165,13 @@ function AppShellContent({
 
   // Transient placeholder while the real SessionSummary loads, so the composer
   // does not flash a value the session never had.
-  const activeSessionForView: SessionSummary | undefined =
-    activeSession ??
-    (activeId
-      ? pendingSessionView({
-          sessionId: activeId,
-          name: shellCopy.newConversation,
-          permissionMode: newTaskPermissionMode,
-        })
-      : undefined);
+  const activeSessionForView = activeSession ?? (activeId
+    ? pendingSessionView({
+        sessionId: activeId,
+        name: shellCopy.newConversation,
+        permissionMode: newTaskPermissionMode,
+      })
+    : undefined);
   // Each control reads its own field. There is nothing to project and nothing
   // to keep in sync: a Session in Plan with Swarm as its orchestration default
   // says both, because it is both.
@@ -3003,6 +2999,7 @@ function AppShellContent({
                   activeModel={activeModel}
                   activeModelLabel={activeModelLabel}
                   activeProviderType={activeConnection?.providerType}
+                  messages={messages}
                   modelChoices={chatModelChoices}
                   modelSwitchHasHistory={modelSwitchHasHistory}
                   hideUnavailableCurrentModel={sessionHealthNotice?.onClickTarget === 'model_picker'}

apps/desktop/src/renderer/chat-composer-region.tsx

@@ -114,6 +114,10 @@ interface ChatComposerRegionProps
   respondToUserQuestion: ComponentProps<typeof UserQuestionPrompt>['onRespond'];
   stop: ComponentProps<typeof UserQuestionPrompt>['onStop'];
   boundaryUnreadableNotice?: BoundaryUnreadableNotice;
+  messages: readonly {
+    type: string;
+    lastRequestAnchor?: { inputTokens: number; outputTokens?: number };
+  }[];
   directoryComposerProps: Pick<
     ComponentProps<typeof Composer>,
     'pendingDirectories' | 'onRemoveDirectory' | 'onPickDirectory'
@@ -135,6 +139,7 @@ export function ChatComposerRegion({
   respondToUserQuestion,
   stop,
   boundaryUnreadableNotice,
+  messages,
   directoryComposerProps,
   directoryPickerEnabled,
   ...composerRest
@@ -145,6 +150,27 @@ export function ChatComposerRegion({
   const activeClientCapability =
     activeInteraction?.type === 'client_capability_request' ? activeInteraction : undefined;
   const activeQuestion = activeInteraction?.type === 'user_question_request' ? activeInteraction : undefined;
+  const latestTokenUsage = [...messages].reverse().find((message) => message.type === 'token_usage');
+  const latestRequestAnchor = latestTokenUsage?.lastRequestAnchor;
+  const activeModelChoice = composerRest.activeModel
+    ? composerRest.modelChoices?.find(
+        (choice) =>
+          choice.connectionId === composerRest.activeModelConnectionId &&
+          choice.model === composerRest.activeModel,
+      )
+    : undefined;
+  const contextUsage = activeId
+    ? {
+        usageTokens:
+          latestRequestAnchor &&
+          Number.isFinite(latestRequestAnchor.inputTokens) &&
+          latestRequestAnchor.inputTokens > 0
+            ? latestRequestAnchor.inputTokens + Math.max(0, latestRequestAnchor.outputTokens ?? 0)
+            : undefined,
+        declaredContextWindow: activeModelChoice?.declaredContextWindow,
+        metadataContextWindow: activeModelChoice?.contextWindow,
+      }
+    : undefined;
   const previousNewTaskDraftKey = useRef(newTaskDraftKey);
   useLayoutEffect(() => {
     const previous = previousNewTaskDraftKey.current;
@@ -254,6 +280,7 @@ export function ChatComposerRegion({
           <Composer
             ref={composerRef}
             {...composerRest}
+            contextUsage={contextUsage}
             // AppShell carries staged attachments into both queued and steering
             // follow-ups. Other Composer hosts remain gated by default because a
             // text-only running-turn submission would leave attachments behind.

apps/desktop/src/renderer/styles/model-switcher.css

@@ -26,6 +26,20 @@
   max-width: 100%;
 }
 
+.maka-context-usage-indicator {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  min-width: 4ch;
+  color: var(--muted-foreground);
+  font: var(--maka-text-supporting);
+  white-space: nowrap;
+}
+
+.maka-context-usage-indicator svg {
+  flex: 0 0 auto;
+}
+
 /* The composer footer's model and thinking pickers are ghost-button
    DropdownMenus — the same toolbar primitive as ＋ and permission, so their
    resting, hover, focus, and disabled chrome all derive from the Astryx

packages/core/src/__tests__/llm-connections.test.ts

@@ -288,6 +288,39 @@ test('chat model choices project exact vision support for attachment composition
   );
 });
 
+test('chat model choices keep provider metadata separate from user context declarations', () => {
+  const choices = chatModelChoicesFor([
+    {
+      connectionId: 'connection-context',
+      slug: 'openai-compatible',
+      name: 'OpenAI compatible',
+      providerType: 'openai-compatible',
+      enabled: true,
+      defaultModel: 'declared-model',
+      enabledModelIds: ['declared-model', 'reported-model'],
+      models: [
+        { id: 'declared-model', contextWindow: 64_000, inputLimit: 48_000 },
+        { id: 'reported-model', contextWindow: 128_000 },
+      ],
+      relayModelProfiles: { 'declared-model': { contextWindow: 32_000 } },
+      createdAt: 1,
+      updatedAt: 1,
+    },
+  ]);
+
+  assert.deepEqual(
+    choices.map(({ model, contextWindow, declaredContextWindow }) => ({
+      model,
+      contextWindow,
+      declaredContextWindow,
+    })),
+    [
+      { model: 'declared-model', contextWindow: 64_000, declaredContextWindow: 32_000 },
+      { model: 'reported-model', contextWindow: 128_000, declaredContextWindow: undefined },
+    ],
+  );
+});
+
 test('provider recognition does not resolve inherited object members', () => {
   // `PROVIDER_REGISTRY` is an object literal, so plain indexing answers truthy
   // for `__proto__` / `toString` / `constructor` and they would read as

packages/core/src/chat-model-choice.ts

@@ -17,7 +17,7 @@
  * under the License.
  */
 
-import { type ThinkingLevel } from './model-thinking.js';
+import { declaredContextWindow, type ThinkingLevel } from './model-thinking.js';
 import {
   offerableCatalogEntries,
   providerDefaultsOf,
@@ -40,6 +40,10 @@ export interface ChatModelChoice {
   thinkingLevels: readonly ThinkingLevel[];
   /** Exact capability projection used by model-facing attachment composition. */
   supportsVision?: boolean;
+  /** Provider/model metadata shown beside the user-declared context setting. */
+  contextWindow?: number;
+  /** User-declared context target, if this model has one. */
+  declaredContextWindow?: number;
 }
 
 export function buildChatModelChoices(
@@ -50,6 +54,7 @@ export function buildChatModelChoices(
     const provider = providerDefaultsOf(connection.providerType);
     if (!provider) continue;
     for (const entry of offerableCatalogEntries(connection)) {
+      const declaredWindow = declaredContextWindow(connection, entry.id);
       choices.push({
         connectionId: connection.connectionId,
         connectionSlug: connection.slug,
@@ -63,6 +68,8 @@ export function buildChatModelChoices(
         isDefault: entry.isDefault,
         thinkingLevels: entry.thinkingLevels,
         supportsVision: entry.supportsVision,
+        ...(entry.contextWindow !== undefined ? { contextWindow: entry.contextWindow } : {}),
+        ...(declaredWindow !== undefined ? { declaredContextWindow: declaredWindow } : {}),
       });
     }
   }

packages/ui/src/composer.tsx

@@ -37,6 +37,7 @@ import { useMountedRef } from './use-mounted-ref.js';
 import {
   ICON_SIZE,
   ArrowUp,
+  CircleGauge,
   FileText,
   ListTodo,
   Network,
@@ -397,6 +398,12 @@ export const Composer = forwardRef<
     noModelConnection?: boolean;
     /** Optional Host-aware replacement for the generic no-model hint. */
     noModelHint?: string;
+    /** Read-only usage indicator for the active model's latest request. */
+    contextUsage?: {
+      usageTokens?: number;
+      declaredContextWindow?: number;
+      metadataContextWindow?: number;
+    };
     /**
      * Optional edit-and-resend banner above the composer. Desktop owns the
      * revision draft; Composer only renders the notice + cancel affordance.
@@ -2078,6 +2085,7 @@ export const Composer = forwardRef<
                     onChange={props.onNewChatThinkingLevelChange}
                   />
                 )}
+                {props.contextUsage ? <ContextUsageIndicator {...props.contextUsage} /> : null}
               </div>
               {/* The project decides where a NEW chat starts, which makes it a
                   parameter of this send like the model beside it — so it sits
@@ -2177,4 +2185,31 @@ export const Composer = forwardRef<
   );
 });
 
+function ContextUsageIndicator(props: {
+  usageTokens?: number;
+  declaredContextWindow?: number;
+  metadataContextWindow?: number;
+}) {
+  const copy = getConversationCopy(useUiLocale()).messages;
+  const label =
+    props.usageTokens === undefined
+      ? '—'
+      : props.declaredContextWindow !== undefined
+        ? `${Math.round((props.usageTokens / props.declaredContextWindow) * 100)}%`
+        : `${props.usageTokens} tok`;
+  const tooltip =
+    props.usageTokens === undefined
+      ? copy.systemNotes.contextUsageUnavailable
+      : props.declaredContextWindow === undefined
+        ? copy.systemNotes.contextUsageProviderUnknown(props.metadataContextWindow)
+        : undefined;
+  const indicator = (
+    <span className="maka-context-usage-indicator" aria-label={tooltip ?? label}>
+      <CircleGauge size={ICON_SIZE.meta} aria-hidden="true" />
+      <span>{label}</span>
+    </span>
+  );
+  return tooltip ? <Tooltip content={tooltip}>{indicator}</Tooltip> : indicator;
+}
+
 export type ComposerProps = ComponentProps<typeof Composer>;

packages/ui/src/conversation-copy.ts

@@ -322,6 +322,8 @@ export interface ConversationCopy {
       contextCompactionFailedOpen: string;
       contextProviderDropping: string;
       contextWindowSuggestion: (tokens: number, declared: number | undefined) => string;
+      contextUsageProviderUnknown: (metadata: number | undefined) => string;
+      contextUsageUnavailable: string;
       stepLimit: string;
     };
   };
@@ -539,6 +541,11 @@ const CONVERSATION_COPY = {
           declared === undefined
             ? `供应商拒绝了这次请求。该模型未声明上下文窗口；上次成功的用量约 ${tokens} tokens，可将窗口设为该值让 Maka 先行压缩。`
             : `供应商拒绝了这次请求，但用量（约 ${tokens} tokens）低于你声明的窗口（${declared}）。声明值可能大于供应商实际窗口，建议下调到 ${tokens}。`,
+        contextUsageProviderUnknown: (metadata) =>
+          metadata === undefined
+            ? '该模型未声明窗口'
+            : `该模型未声明窗口；模型声明 ${metadata}`,
+        contextUsageUnavailable: '供应商未报告用量',
         stepLimit: '已达到本轮工具步骤上限，任务可能尚未完成。发送“继续”即可接着处理。',
       },
     },
@@ -702,6 +709,11 @@ const CONVERSATION_COPY = {
           declared === undefined
             ? `The provider rejected this request. No context window is declared for this model; the last accepted usage was about ${tokens} tokens — set the window to that value so Maka compacts first.`
             : `The provider rejected this request at about ${tokens} tokens, below your declared window (${declared}). The declared value is likely larger than the provider's; consider lowering it to ${tokens}.`,
+        contextUsageProviderUnknown: (metadata) =>
+          metadata === undefined
+            ? 'No context window is declared for this model'
+            : `No context window is declared for this model; model metadata declares ${metadata}`,
+        contextUsageUnavailable: 'The provider did not report usage',
         stepLimit: 'Reached the configured step limit. The task may be incomplete. Send “continue” to resume.',
       },
     },