@robota-sdk/agent-command 3.0.0-beta.79 → 3.0.0-beta.81

package/src/context/__tests__/context-command-module.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it, vi } from 'vitest';
-import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import {
+  createAssistantMessage,
+  createToolMessage,
+  createUserMessage,
+  messageToHistoryEntry,
+} from '@robota-sdk/agent-core';
+import type { IHistoryEntry, IToolSchema } from '@robota-sdk/agent-core';
 import type {
   ICommandHostContext,
   ICommandSessionRuntime,
@@ -8,11 +14,16 @@ import type {
   IContextReferenceRemoveResult,
   TAutoCompactThresholdSource,
 } from '@robota-sdk/agent-framework';
-import type { IContextReferenceItem } from '@robota-sdk/agent-interface-transport';
-import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import type { IContextReferenceItem } from '@robota-sdk/agent-interface-session';
+import { CommandRegistry, SystemCommandExecutor } from '@robota-sdk/agent-framework';
 import { createContextCommandModule } from '../context-command-module.js';
+import type { ICommandHostContextWindow } from '@robota-sdk/agent-framework';
+import {
+  createTestCommandHost,
+  createTestSessionRuntime,
+} from '@robota-sdk/agent-framework/testing';
 
-type TContextWindowState = ReturnType<ICommandHostContext['getContextState']>;
+type TContextWindowState = ReturnType<ICommandHostContextWindow['getContextState']>;
 type TPermissionMode = ReturnType<ICommandSessionRuntime['getPermissionMode']>;
 
 const CONTEXT_STATE: TContextWindowState = {
@@ -58,12 +69,9 @@ const SYSTEM_REFERENCE: IContextReferenceItem = {
   lastUsedAt: '2026-05-05T00:00:00.000Z',
 };
 
-function createRuntime(
-  state: { threshold: number | false },
-  history: IHistoryEntry[] = [],
-): ICommandSessionRuntime {
+function createRuntime(state: { threshold: number | false }, history: IHistoryEntry[] = []) {
   let mode: TPermissionMode = 'default';
-  return {
+  return createTestSessionRuntime({
     clearHistory: vi.fn(),
     compact: vi.fn().mockResolvedValue(undefined),
     getContextState: () => CONTEXT_STATE,
@@ -80,10 +88,12 @@ function createRuntime(
     setAutoCompactThreshold: (threshold) => {
       state.threshold = threshold;
     },
-  };
+  });
 }
 
-function createCommandHostContext(threshold: number | false = 0.835): ICommandHostContext & {
+function createCommandHostContext(threshold: number | false = 0.835): ReturnType<
+  typeof createTestCommandHost
+> & {
   settings: Record<string, number | false>;
   source: TAutoCompactThresholdSource;
   references: IContextReferenceItem[];
@@ -96,6 +106,63 @@ function createCommandHostContext(threshold: number | false = 0.835): ICommandHo
   };
   const runtime = createRuntime(state);
   return {
+    ...createTestCommandHost({
+      overrides: {
+        getSession: () => runtime,
+        getContextState: () => CONTEXT_STATE,
+        getAutoCompactThreshold: () => state.threshold,
+        getAutoCompactThresholdSource: () => state.source,
+        setAutoCompactThreshold: (nextThreshold, source = 'session') => {
+          state.threshold = nextThreshold;
+          state.source = source;
+        },
+        getCommandHostAdapters: () => ({
+          settings: {
+            read: () => state.settings,
+            write: (settings) => {
+              const value = settings.autoCompactThreshold;
+              state.settings =
+                typeof value === 'number' || value === false ? { autoCompactThreshold: value } : {};
+            },
+          },
+        }),
+        compactContext: vi.fn(),
+        listContextReferences: () => [...state.references],
+        addContextReference: async (path): Promise<IContextReferenceAddResult> => {
+          const reference = {
+            ...MANUAL_REFERENCE,
+            relativePath: path,
+            sourcePath: `/workspace/${path}`,
+            originalReference: `@${path}`,
+          };
+          state.references = [...state.references, reference];
+          return { reference, evicted: [], diagnostics: [] };
+        },
+        removeContextReference: (path): IContextReferenceRemoveResult => {
+          const removed = state.references.find((reference) => reference.relativePath === path);
+          state.references = state.references.filter(
+            (reference) => reference.relativePath !== path,
+          );
+          return removed ? { removed } : {};
+        },
+        clearContextReferences: (): IContextReferenceClearResult => {
+          const removed = [...state.references];
+          state.references = [];
+          return { removed };
+        },
+        getCwd: () => '/workspace',
+        listCommands: () => [],
+        listEditCheckpoints: () => [],
+        restoreEditCheckpoint: vi.fn(),
+        rollbackEditCheckpoint: vi.fn(),
+        getUsedMemoryReferences: () => [],
+        recordMemoryEvent: vi.fn(),
+        listBackgroundTasks: () => [],
+        readBackgroundTaskLog: vi.fn().mockResolvedValue({ taskId: 'task_1', lines: [] }),
+        cancelBackgroundTask: vi.fn(),
+        closeBackgroundTask: vi.fn(),
+      },
+    }),
     get settings() {
       return state.settings;
     },
@@ -105,57 +172,6 @@ function createCommandHostContext(threshold: number | false = 0.835): ICommandHo
     get references() {
       return state.references;
     },
-    getSession: () => runtime,
-    getContextState: () => CONTEXT_STATE,
-    getAutoCompactThreshold: () => state.threshold,
-    getAutoCompactThresholdSource: () => state.source,
-    setAutoCompactThreshold: (nextThreshold, source = 'session') => {
-      state.threshold = nextThreshold;
-      state.source = source;
-    },
-    getCommandHostAdapters: () => ({
-      settings: {
-        read: () => state.settings,
-        write: (settings) => {
-          const value = settings.autoCompactThreshold;
-          state.settings =
-            typeof value === 'number' || value === false ? { autoCompactThreshold: value } : {};
-        },
-      },
-    }),
-    compactContext: vi.fn(),
-    listContextReferences: () => [...state.references],
-    addContextReference: async (path): Promise<IContextReferenceAddResult> => {
-      const reference = {
-        ...MANUAL_REFERENCE,
-        relativePath: path,
-        sourcePath: `/workspace/${path}`,
-        originalReference: `@${path}`,
-      };
-      state.references = [...state.references, reference];
-      return { reference, evicted: [], diagnostics: [] };
-    },
-    removeContextReference: (path): IContextReferenceRemoveResult => {
-      const removed = state.references.find((reference) => reference.relativePath === path);
-      state.references = state.references.filter((reference) => reference.relativePath !== path);
-      return removed ? { removed } : {};
-    },
-    clearContextReferences: (): IContextReferenceClearResult => {
-      const removed = [...state.references];
-      state.references = [];
-      return { removed };
-    },
-    getCwd: () => '/workspace',
-    listCommands: () => [],
-    listEditCheckpoints: () => [],
-    restoreEditCheckpoint: vi.fn(),
-    rollbackEditCheckpoint: vi.fn(),
-    getUsedMemoryReferences: () => [],
-    recordMemoryEvent: vi.fn(),
-    listBackgroundTasks: () => [],
-    readBackgroundTaskLog: vi.fn().mockResolvedValue({ taskId: 'task_1', lines: [] }),
-    cancelBackgroundTask: vi.fn(),
-    closeBackgroundTask: vi.fn(),
   };
 }
 
@@ -164,6 +180,34 @@ function createExecutor(): SystemCommandExecutor {
 }
 
 describe('createContextCommandModule', () => {
+  it('preserves argument hints and specialized subcommands in both command projections', () => {
+    const module = createContextCommandModule();
+    const registry = new CommandRegistry();
+    registry.addModule(module);
+    const executor = new SystemCommandExecutor([...(module.systemCommands ?? [])]);
+    const entry = registry.getCommands().find((command) => command.name === 'context');
+    const command = executor.getCommand('context');
+    expect(entry?.argumentHint).toBe('list | add <path> | remove <path> | clear | auto ...');
+    expect(command?.argumentHint).toBe('list | add <path> | remove <path> | clear | auto ...');
+    expect(command?.subcommands?.map((subcommand) => subcommand.name)).toEqual([
+      'list',
+      'add',
+      'remove',
+      'clear',
+      'auto',
+    ]);
+    expect(command?.subcommands).toEqual(registry.getSubcommands('context'));
+    expect(command).toMatchObject({
+      modelInvocable: true,
+      userInvocable: true,
+      requiresPermission: false,
+    });
+    expect(command?.lifecycle ?? 'inline').toBe('inline');
+    expect(command?.description).toBe(entry?.description);
+    expect(command?.modelDescription).toBe(entry?.modelDescription);
+    expect(executor.isModelInvocable('context')).toBe(true);
+  });
+
   it('provides context metadata and an executable command', () => {
     const module = createContextCommandModule();
     const command = module.systemCommands?.[0];
@@ -179,7 +223,7 @@ describe('createContextCommandModule', () => {
     expect(command).toEqual(
       expect.objectContaining({
         name: 'context',
-        modelInvocable: false,
+        modelInvocable: true,
       }),
     );
   });
@@ -335,6 +379,39 @@ describe('createContextCommandModule', () => {
     expect(result?.message).toContain('References: 2 active, 0 observed');
   });
 
+  it('lists only the tool results still in context, not turns compaction summarized away', async () => {
+    const call = (id: string, name: string, arg: string) =>
+      createAssistantMessage(null, {
+        toolCalls: [
+          { id, type: 'function', function: { name, arguments: JSON.stringify({ path: arg }) } },
+        ],
+      });
+    const compacted = [
+      createUserMessage('old task'),
+      call('old-1', 'Read', 'compacted-away.ts'),
+      createToolMessage('old result', { toolCallId: 'old-1' }),
+    ];
+    const live = [
+      createUserMessage('new task'),
+      call('new-1', 'Read', 'still-live.ts'),
+      createToolMessage('new result', { toolCallId: 'new-1' }),
+    ];
+    const runtime = createTestSessionRuntime({
+      getContextState: () => CONTEXT_STATE,
+      getFullHistory: () => [...compacted, ...live].map(messageToHistoryEntry),
+      getHistory: () => live,
+    });
+    const context = createTestCommandHost({
+      overrides: { getSession: () => runtime, getContextState: () => CONTEXT_STATE },
+    });
+
+    const result = await createExecutor().execute('context', context, 'list');
+
+    expect(result?.message).toContain('still-live.ts');
+    expect(result?.message).not.toContain('compacted-away.ts');
+    expect(result?.message).toContain('Conversation history — 1 turn |');
+  });
+
   it('shows full context breakdown with empty sections when no references', async () => {
     const context = createCommandHostContext();
 
@@ -349,3 +426,77 @@ describe('createContextCommandModule', () => {
     expect(result?.message).not.toContain('~');
   });
 });
+
+/**
+ * CLI-1990 TC-12 — `/context` reports what the TOOL SCHEMAS cost.
+ *
+ * Before this, no surface separated the tool schemas from the system prompt they are billed
+ * alongside: `estimateSerializedContextTokens` covered messages only, and the tool line in the
+ * breakdown counted tool RESULTS. So the saving deferral exists to produce had no observable at all.
+ * These cases pin the figure and, crucially, that it FALLS when tools are deferred — a smaller
+ * offered set is a smaller request, which is the whole claim.
+ */
+function toolSchema(name: string): IToolSchema {
+  return {
+    name,
+    description: `the ${name} tool, described at a realistic length for a request`,
+    parameters: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'what to operate on' } },
+    },
+  };
+}
+
+function createHostWithTools(schemas: IToolSchema[]) {
+  const runtime = createTestSessionRuntime({
+    getContextState: () => CONTEXT_STATE,
+    getOfferedToolSchemas: () => schemas,
+  });
+  return createTestCommandHost({
+    overrides: {
+      getSession: () => runtime,
+      getContextState: () => CONTEXT_STATE,
+      listContextReferences: () => [],
+    },
+  });
+}
+
+describe('CLI-1990 TC-12 — /context reports toolSchemaTokens', () => {
+  it('reports a figure greater than zero for a session with tools', async () => {
+    const context = createHostWithTools([toolSchema('Read'), toolSchema('Write')]);
+
+    const result = await createExecutor().execute('context', context, 'list');
+
+    expect(result?.success).toBe(true);
+    const tokens = (result?.data as { toolSchemaTokens: number }).toolSchemaTokens;
+    expect(tokens).toBeGreaterThan(0);
+    expect(result?.message).toContain('Tool schemas (sent every turn)');
+    expect(result?.message).toContain('Read');
+    expect(result?.message).toContain('Write');
+  });
+
+  it('reports a SMALLER figure when tools are deferred — the saving, made observable', async () => {
+    const all = [toolSchema('Read'), toolSchema('Write'), toolSchema('Grep')];
+    const full = await createExecutor().execute('context', createHostWithTools(all), 'list');
+    // With deferral engaged the withheld schemas are not in the offered set, so they are not sent.
+    const deferred = await createExecutor().execute(
+      'context',
+      createHostWithTools(all.slice(0, 1)),
+      'list',
+    );
+
+    const fullTokens = (full?.data as { toolSchemaTokens: number }).toolSchemaTokens;
+    const deferredTokens = (deferred?.data as { toolSchemaTokens: number }).toolSchemaTokens;
+    expect(deferredTokens).toBeGreaterThan(0);
+    expect(deferredTokens).toBeLessThan(fullTokens);
+  });
+
+  it('reports zero, and no token label, for a session offering no tools', async () => {
+    const context = createHostWithTools([]);
+
+    const result = await createExecutor().execute('context', context, 'list');
+
+    expect((result?.data as { toolSchemaTokens: number }).toolSchemaTokens).toBe(0);
+    expect(result?.message).toContain('Tool schemas (sent every turn):\n  (none)');
+  });
+});

package/src/context/auto-compact-format.ts

@@ -0,0 +1,25 @@
+/**
+ * Leaf formatting helpers for the auto-compact threshold line. Split out of `context-command.ts`
+ * so `context-breakdown.ts` can use {@link formatAutoCompactLine} without importing back from
+ * `context-command.ts`, which previously created an import cycle between the two.
+ */
+import type { TAutoCompactThreshold, TAutoCompactThresholdSource } from '@robota-sdk/agent-framework';
+
+const PERCENT = 100;
+
+export function formatThreshold(threshold: TAutoCompactThreshold): string {
+  if (threshold === false) {
+    return 'disabled';
+  }
+  return `${Math.round(threshold * PERCENT)}%`;
+}
+
+export function formatAutoCompactLine(
+  threshold: TAutoCompactThreshold,
+  source: TAutoCompactThresholdSource,
+): string {
+  if (threshold === false) {
+    return `Auto compact: disabled (${source})`;
+  }
+  return `Auto compact: ${formatThreshold(threshold)} (${source})`;
+}

package/src/context/context-breakdown.ts

@@ -0,0 +1,295 @@
+/**
+ * The `/context` transcript breakdown: token accounting over the history plus its rendering.
+ *
+ * Split out of `context-command.ts` when that file passed its size floor. The seam is a real one and
+ * the role ports named it: this half only READS (`TContextReadHost`), while the command surface it
+ * came from dispatches subcommands and writes thresholds and references.
+ */
+
+import { CONTEXT_ESTIMATE_CHARS_PER_TOKEN, estimateToolSchemaTokens } from '@robota-sdk/agent-core';
+import {
+  listCommandContextReferences,
+  readAutoCompactThreshold,
+  readAutoCompactThresholdSource,
+  readCommandContextState,
+} from '@robota-sdk/agent-framework';
+
+import { formatAutoCompactLine } from './auto-compact-format.js';
+
+import type { IHistoryEntry, TUniversalMessage } from '@robota-sdk/agent-core';
+import type {
+  ICommandHostContextReferences,
+  ICommandHostContextWindow,
+  ICommandHostSessionAccess,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IContextReferenceItem } from '@robota-sdk/agent-interface-session';
+
+/** What the breakdown reads — no adapter role, no writes. */
+type TContextReadHost = ICommandHostContextReferences &
+  ICommandHostContextWindow &
+  ICommandHostSessionAccess;
+
+const TOOL_ARG_MAX_LEN = 60;
+
+function estimateTokens(charLength: number): number {
+  return Math.ceil(charLength / CONTEXT_ESTIMATE_CHARS_PER_TOKEN);
+}
+
+export function formatContextReferenceLine(reference: IContextReferenceItem): string {
+  return [
+    reference.relativePath,
+    `[${reference.loadType}, ${reference.status}]`,
+    `~${estimateTokens(reference.byteLength).toLocaleString()} tokens`,
+  ].join(' ');
+}
+
+// ── History analysis ────────────────────────────────────────────────────────
+
+interface IToolResultSummary {
+  toolName: string;
+  displayArg: string;
+}
+
+interface IMessageTokensByRole {
+  systemTokens: number;
+  userTokens: number;
+  userCount: number;
+  assistantTokens: number;
+  assistantCount: number;
+  toolTokens: number;
+  toolCallCount: number;
+  totalTokens: number;
+}
+
+interface IToolDisplayList {
+  turnCount: number;
+  toolResults: IToolResultSummary[];
+  totalToolCallCount: number;
+}
+
+function parseToolCallArgs(argsJson: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(argsJson) as Record<string, unknown>;
+  } catch {
+    // allow-fallback: tool call arguments JSON may be malformed; display-only degradation, not a terminal path
+    return null;
+  }
+}
+
+function extractFirstToolArg(argsJson: string): string {
+  const parsed = parseToolCallArgs(argsJson);
+  if (parsed === null) return '';
+  const first = Object.values(parsed)[0];
+  const raw = typeof first === 'string' ? first : JSON.stringify(first);
+  return raw.length > TOOL_ARG_MAX_LEN ? `${raw.slice(0, TOOL_ARG_MAX_LEN)}…` : raw;
+}
+
+function computeMessageTokensByRole(rawMessages: TUniversalMessage[]): IMessageTokensByRole {
+  let systemTokens = 0;
+  let userTokens = 0;
+  let userCount = 0;
+  let assistantTokens = 0;
+  let assistantCount = 0;
+  let toolTokens = 0;
+  let toolCallCount = 0;
+
+  for (const msg of rawMessages) {
+    const t = Math.ceil(JSON.stringify(msg).length / CONTEXT_ESTIMATE_CHARS_PER_TOKEN);
+    if (msg.role === 'system') {
+      systemTokens += t;
+    } else if (msg.role === 'user') {
+      userTokens += t;
+      userCount++;
+    } else if (msg.role === 'assistant') {
+      assistantTokens += t;
+      assistantCount++;
+    } else if (msg.role === 'tool') {
+      toolTokens += t;
+      toolCallCount++;
+    }
+  }
+
+  return {
+    systemTokens,
+    userTokens,
+    userCount,
+    assistantTokens,
+    assistantCount,
+    toolTokens,
+    toolCallCount,
+    totalTokens: systemTokens + userTokens + assistantTokens + toolTokens,
+  };
+}
+
+/** One conversation item as the display reads it: its role and its message payload. */
+interface IChatItem {
+  readonly type: string;
+  readonly data: unknown;
+}
+
+/** Every chat entry of the full history, including turns compaction has since summarized away. */
+export function buildToolDisplayList(history: IHistoryEntry[]): IToolDisplayList {
+  return buildDisplayList(
+    history
+      .filter((entry) => entry.category === 'chat')
+      .map((entry) => ({ type: entry.type, data: entry.data })),
+  );
+}
+
+/** Only what the model still has in context — what `/context list` accounts for. */
+export function buildLiveToolDisplayList(messages: readonly TUniversalMessage[]): IToolDisplayList {
+  return buildDisplayList(messages.map((message) => ({ type: message.role, data: message })));
+}
+
+function buildDisplayList(items: readonly IChatItem[]): IToolDisplayList {
+  type TToolCallEntry = { name: string; firstArg: string };
+  const toolCallMap = new Map<string, TToolCallEntry>();
+
+  for (const entry of items) {
+    if (entry.type !== 'assistant') continue;
+    const data = entry.data as {
+      toolCalls?: Array<{ id: string; function: { name: string; arguments: string } }>;
+    };
+    for (const tc of data.toolCalls ?? []) {
+      toolCallMap.set(tc.id, {
+        name: tc.function.name,
+        firstArg: extractFirstToolArg(tc.function.arguments),
+      });
+    }
+  }
+
+  let turnCount = 0;
+  let totalToolCallCount = 0;
+  const toolDisplayMap = new Map<string, IToolResultSummary>();
+
+  for (const entry of items) {
+    if (entry.type === 'user') {
+      turnCount++;
+    } else if (entry.type === 'tool') {
+      const data = entry.data as { toolCallId?: string };
+      const tc = toolCallMap.get(data.toolCallId ?? '');
+      const toolName = tc?.name ?? 'tool';
+      const displayArg = tc?.firstArg ?? '';
+      totalToolCallCount++;
+      toolDisplayMap.set(`${toolName}:${displayArg}`, { toolName, displayArg });
+    }
+  }
+
+  return {
+    turnCount,
+    toolResults: [...toolDisplayMap.values()],
+    totalToolCallCount,
+  };
+}
+
+// ── Full context breakdown (for /context list) ──────────────────────────────
+
+function formatSection(title: string, tokens: number, lines: string[]): string {
+  const tokenLabel = tokens > 0 ? ` — ~${tokens.toLocaleString()} tokens` : '';
+  const header = `${title}${tokenLabel}:`;
+  return lines.length === 0
+    ? `${header}\n  (none)`
+    : [header, ...lines.map((l) => `  ${l}`)].join('\n');
+}
+
+export function formatFullContextBreakdown(context: TContextReadHost): ICommandResult {
+  const state = readCommandContextState(context);
+  const autoCompactThreshold = readAutoCompactThreshold(context);
+  const autoCompactThresholdSource = readAutoCompactThresholdSource(context);
+  const rawMessages = context.getSession().getHistory();
+  const msgTokens = computeMessageTokensByRole(rawMessages);
+  // CLI-1990: what the TOOL SCHEMAS cost on every request — the offered set, so a deferred tool that
+  // has not been loaded is not counted, because it is not sent. Until now nothing separated this
+  // from the system prompt it is billed alongside, so the saving deferral produces had no observable.
+  const offeredToolSchemas = context.getSession().getOfferedToolSchemas();
+  const toolSchemaTokens = estimateToolSchemaTokens(offeredToolSchemas);
+  // The live messages, like the token counts beside it: a turn compaction summarized away is no
+  // longer in context, so listing its tool results would describe a context the model does not have.
+  const display = buildLiveToolDisplayList(rawMessages);
+  const references = listCommandContextReferences(context);
+
+  const systemRefs = references.filter((r) => r.loadType === 'system');
+  const manualRefs = references.filter((r) => r.loadType === 'manual');
+  const promptRefs = references.filter((r) => r.loadType === 'prompt-reference');
+
+  const systemRefTokens = systemRefs.reduce((s, r) => s + estimateTokens(r.byteLength), 0);
+  const manualTokens = manualRefs.reduce((s, r) => s + estimateTokens(r.byteLength), 0);
+  const promptRefTokens = promptRefs.reduce((s, r) => s + estimateTokens(r.byteLength), 0);
+
+  const convTurnLabel =
+    display.turnCount === 0
+      ? 'Conversation history — 0 turns'
+      : `Conversation history — ${display.turnCount} turn${display.turnCount !== 1 ? 's' : ''} | ~${msgTokens.totalTokens.toLocaleString()} tokens`;
+
+  const toolResultLines = display.toolResults.map(
+    (t) => `${t.toolName}${t.displayArg ? `: ${t.displayArg}` : ''}`,
+  );
+
+  const uniqueToolCount = display.toolResults.length;
+  const totalToolCallCount = display.totalToolCallCount;
+  const toolResultsLabel =
+    totalToolCallCount === 0
+      ? 'Tool results (0): (none)'
+      : uniqueToolCount < totalToolCallCount
+        ? `Tool results (${uniqueToolCount} unique / ${totalToolCallCount} calls, ~${msgTokens.toolTokens.toLocaleString()} tokens):`
+        : `Tool results (${uniqueToolCount}, ~${msgTokens.toolTokens.toLocaleString()} tokens):`;
+
+  const conversationLines: string[] =
+    display.turnCount === 0
+      ? []
+      : [
+          `User (${msgTokens.userCount}): ~${msgTokens.userTokens.toLocaleString()} tokens`,
+          `Assistant (${msgTokens.assistantCount}): ~${msgTokens.assistantTokens.toLocaleString()} tokens`,
+          ...(msgTokens.systemTokens > 0
+            ? [`System messages: ~${msgTokens.systemTokens.toLocaleString()} tokens`]
+            : []),
+          totalToolCallCount > 0
+            ? [toolResultsLabel, ...toolResultLines.map((l) => `  ${l}`)].join('\n')
+            : toolResultsLabel,
+        ];
+
+  const convSection =
+    display.turnCount === 0
+      ? `${convTurnLabel}:\n  (none)`
+      : [`${convTurnLabel}:`, ...conversationLines.map((l) => `  ${l}`)].join('\n');
+
+  const message = [
+    `Context: ${state.usedTokens.toLocaleString()} / ${state.maxTokens.toLocaleString()} tokens (${Math.round(state.usedPercentage)}%)`,
+    formatAutoCompactLine(autoCompactThreshold, autoCompactThresholdSource),
+    '',
+    formatSection(
+      'System prompt (active every turn)',
+      systemRefTokens,
+      systemRefs.map(formatContextReferenceLine),
+    ),
+    '',
+    formatSection(
+      'Tool schemas (sent every turn)',
+      toolSchemaTokens,
+      offeredToolSchemas.map((schema) => schema.name),
+    ),
+    '',
+    convSection,
+    '',
+    formatSection('Manually added', manualTokens, manualRefs.map(formatContextReferenceLine)),
+    '',
+    formatSection(
+      'Prompt references (@-syntax)',
+      promptRefTokens,
+      promptRefs.map(formatContextReferenceLine),
+    ),
+  ].join('\n');
+
+  return {
+    success: true,
+    message,
+    data: {
+      references,
+      history: { turnCount: display.turnCount, toolResults: display.toolResults },
+      // CLI-1990: machine-readable beside the rendered line, so a caller can compare the figure
+      // across configurations rather than parsing the message back out.
+      toolSchemaTokens,
+    },
+  };
+}