@robota-sdk/agent-command 3.0.0-beta.68 → 3.0.0-beta.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-command",
-  "version": "3.0.0-beta.68",
+  "version": "3.0.0-beta.70",
   "description": "Consolidated command module implementations for Robota SDK CLI",
   "type": "module",
   "main": "dist/node/index.js",
@@ -24,8 +24,8 @@
     "src"
   ],
   "dependencies": {
-    "@robota-sdk/agent-core": "3.0.0-beta.68",
-    "@robota-sdk/agent-framework": "3.0.0-beta.68"
+    "@robota-sdk/agent-core": "3.0.0-beta.70",
+    "@robota-sdk/agent-framework": "3.0.0-beta.70"
   },
   "devDependencies": {
     "@types/node": "^22.14.0",

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

@@ -27,6 +27,7 @@ function createSessionRuntime(): ICommandSessionRuntime {
     getMessageCount: () => 0,
     getSessionAllowedTools: () => [],
     getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
   };
 }
 

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

@@ -35,6 +35,7 @@ function createRuntime(beforeCount = 10, afterCount = 3): ICommandSessionRuntime
     getMessageCount,
     getSessionAllowedTools: () => [],
     getAutoCompactThreshold: () => 0.835,
+    getFullHistory: () => [],
   };
 }
 

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

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
 import type {
   ICommandHostContext,
   IContextReferenceAddResult,
@@ -45,7 +46,22 @@ const PROMPT_REFERENCE: IContextReferenceItem = {
   lastUsedAt: '2026-05-05T00:00:01.000Z',
 };
 
-function createRuntime(state: { threshold: number | false }): ICommandSessionRuntime {
+const SYSTEM_REFERENCE: IContextReferenceItem = {
+  id: 'system:AGENTS.md',
+  sourcePath: '/workspace/AGENTS.md',
+  relativePath: 'AGENTS.md',
+  originalReference: 'AGENTS.md',
+  loadType: 'system',
+  status: 'active',
+  byteLength: 1024,
+  loadedAt: '2026-05-05T00:00:00.000Z',
+  lastUsedAt: '2026-05-05T00:00:00.000Z',
+};
+
+function createRuntime(
+  state: { threshold: number | false },
+  history: IHistoryEntry[] = [],
+): ICommandSessionRuntime {
   let mode: TPermissionMode = 'default';
   return {
     clearHistory: vi.fn(),
@@ -59,6 +75,7 @@ function createRuntime(state: { threshold: number | false }): ICommandSessionRun
     getMessageCount: () => 1,
     getSessionAllowedTools: () => [],
     getAutoCompactThreshold: () => state.threshold,
+    getFullHistory: () => history,
     setAutoCompactThreshold: (threshold) => {
       state.threshold = threshold;
     },
@@ -190,9 +207,9 @@ describe('createContextCommandModule', () => {
     const result = await createExecutor().execute('context', context, 'list');
 
     expect(result?.success).toBe(true);
-    expect(result?.message).toContain('AGENTS.md [manual, active] 42 B');
+    expect(result?.message).toContain('AGENTS.md [manual, active] ~11 tokens');
     expect(result?.message).toContain(
-      'packages/agent-sdk/docs/SPEC.md [prompt-reference, observed] 200 B',
+      'packages/agent-sdk/docs/SPEC.md [prompt-reference, observed] ~50 tokens',
     );
     expect(result?.data?.references).toEqual([MANUAL_REFERENCE, PROMPT_REFERENCE]);
   });
@@ -203,7 +220,9 @@ describe('createContextCommandModule', () => {
     const result = await createExecutor().execute('context', context, 'add AGENTS.md');
 
     expect(result?.success).toBe(true);
-    expect(result?.message).toContain('Context reference added: AGENTS.md [manual, active] 42 B.');
+    expect(result?.message).toContain(
+      'Context reference added: AGENTS.md [manual, active] ~11 tokens.',
+    );
     expect(context.references[0]?.relativePath).toBe('AGENTS.md');
   });
 
@@ -214,7 +233,9 @@ describe('createContextCommandModule', () => {
     const result = await createExecutor().execute('context', context, 'remove AGENTS.md');
 
     expect(result?.success).toBe(true);
-    expect(result?.message).toBe('Context reference removed: AGENTS.md [manual, active] 42 B.');
+    expect(result?.message).toBe(
+      'Context reference removed: AGENTS.md [manual, active] ~11 tokens.',
+    );
     expect(context.references).toEqual([]);
   });
 
@@ -291,4 +312,39 @@ describe('createContextCommandModule', () => {
     expect(result?.success).toBe(false);
     expect(result?.message).toContain('greater than 0% and at most 100%');
   });
+
+  it('lists system context references with [system, active] label', async () => {
+    const context = createCommandHostContext();
+    context.references.push(SYSTEM_REFERENCE);
+
+    const result = await createExecutor().execute('context', context, 'list');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('AGENTS.md [system, active] ~256 tokens');
+    expect(result?.data?.references).toEqual([SYSTEM_REFERENCE]);
+  });
+
+  it('includes system references in context summary active count', async () => {
+    const context = createCommandHostContext();
+    context.references.push(SYSTEM_REFERENCE, MANUAL_REFERENCE);
+
+    const result = await createExecutor().execute('context', context, '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('References: 2 active, 0 observed');
+  });
+
+  it('shows full context breakdown with empty sections when no references', async () => {
+    const context = createCommandHostContext();
+
+    const result = await createExecutor().execute('context', context, 'list');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('System prompt (active every turn):');
+    expect(result?.message).toContain('Conversation history — 0 turns:');
+    expect(result?.message).toContain('Manually added:');
+    expect(result?.message).toContain('Prompt references (@-syntax):');
+    // All sections empty
+    expect(result?.message).not.toContain('~');
+  });
 });

package/src/context/context-command.ts

@@ -12,6 +12,7 @@ import {
   writeAutoCompactThresholdSetting,
 } from '@robota-sdk/agent-framework';
 
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
 import type {
   ICommandHostContext,
   ICommandResult,
@@ -63,11 +64,15 @@ export async function executeContextCommand(
   const state = readCommandContextState(context);
   const autoCompactThreshold = readAutoCompactThreshold(context);
   const autoCompactThresholdSource = readAutoCompactThresholdSource(context);
+  const history = context.getSession().getFullHistory();
+  const analysis = analyzeHistory(history);
+  const references = listCommandContextReferences(context);
   return {
     message: [
       `Context: ${state.usedTokens.toLocaleString()} / ${state.maxTokens.toLocaleString()} tokens (${Math.round(state.usedPercentage)}%)`,
       formatAutoCompactLine(autoCompactThreshold, autoCompactThresholdSource),
-      formatContextReferenceSummary(listCommandContextReferences(context)),
+      formatContextReferenceSummary(references),
+      `History: ${analysis.turnCount} turn${analysis.turnCount !== 1 ? 's' : ''}`,
     ].join('\n'),
     success: true,
     data: {
@@ -76,7 +81,7 @@ export async function executeContextCommand(
       percentage: state.usedPercentage,
       autoCompactThreshold,
       autoCompactThresholdSource,
-      references: listCommandContextReferences(context),
+      references,
     },
   };
 }
@@ -88,7 +93,7 @@ async function executeContextSubcommand(
   const [subcommand, ...rest] = parts;
   if (subcommand === 'list') {
     if (rest.length > 0) return { success: false, message: USAGE };
-    return formatContextReferenceList(listCommandContextReferences(context));
+    return formatFullContextBreakdown(context);
   }
   if (subcommand === 'add') {
     return executeAddContextReference(context, rest);
@@ -278,22 +283,197 @@ function formatContextReferenceSummary(references: readonly IContextReferenceIte
   return `References: ${active} active, ${observed} observed`;
 }
 
-function formatContextReferenceList(references: readonly IContextReferenceItem[]): ICommandResult {
-  if (references.length === 0) {
-    return { success: true, message: 'No context references.', data: { references } };
-  }
+// 1 token ≈ 4 chars — same approximation used across the codebase (limits-helpers.ts)
+const CHARS_PER_TOKEN = 4;
+const TOOL_ARG_MAX_LEN = 60;
 
-  return {
-    success: true,
-    message: ['Context references:', ...references.map(formatContextReferenceLine)].join('\n'),
-    data: { references },
-  };
+function estimateTokens(charLength: number): number {
+  return Math.ceil(charLength / CHARS_PER_TOKEN);
 }
 
 function formatContextReferenceLine(reference: IContextReferenceItem): string {
   return [
     reference.relativePath,
     `[${reference.loadType}, ${reference.status}]`,
-    `${reference.byteLength.toLocaleString()} B`,
+    `~${estimateTokens(reference.byteLength).toLocaleString()} tokens`,
   ].join(' ');
 }
+
+// ── History analysis ────────────────────────────────────────────────────────
+
+interface IToolResultSummary {
+  toolName: string;
+  displayArg: string;
+  tokens: number;
+}
+
+interface IHistoryAnalysis {
+  turnCount: number;
+  userCount: number;
+  userTokens: number;
+  assistantCount: number;
+  assistantTokens: number;
+  toolResults: IToolResultSummary[];
+  totalTokens: 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 analyzeHistory(history: IHistoryEntry[]): IHistoryAnalysis {
+  type TToolCallEntry = { name: string; firstArg: string };
+  const toolCallMap = new Map<string, TToolCallEntry>();
+
+  for (const entry of history) {
+    if (entry.category !== 'chat' || 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 userCount = 0;
+  let userTokens = 0;
+  let assistantCount = 0;
+  let assistantTokens = 0;
+  const toolResultMap = new Map<string, IToolResultSummary>();
+
+  for (const entry of history) {
+    if (entry.category !== 'chat') continue;
+    if (entry.type === 'user') {
+      const data = entry.data as { content?: string };
+      userCount++;
+      userTokens += estimateTokens((data.content ?? '').length);
+    } else if (entry.type === 'assistant') {
+      const data = entry.data as { content?: string | null; toolCalls?: unknown[] };
+      assistantCount++;
+      assistantTokens += estimateTokens(
+        (data.content ?? '').length + (data.toolCalls ? JSON.stringify(data.toolCalls).length : 0),
+      );
+    } else if (entry.type === 'tool') {
+      const data = entry.data as { content?: string; toolCallId?: string };
+      const tc = toolCallMap.get(data.toolCallId ?? '');
+      const toolName = tc?.name ?? 'tool';
+      const displayArg = tc?.firstArg ?? '';
+      const tokens = estimateTokens((data.content ?? '').length);
+      toolResultMap.set(`${toolName}:${displayArg}`, { toolName, displayArg, tokens });
+    }
+  }
+
+  const toolResults = [...toolResultMap.values()];
+  const toolTokens = toolResults.reduce((s, t) => s + t.tokens, 0);
+  return {
+    turnCount: userCount,
+    userCount,
+    userTokens,
+    assistantCount,
+    assistantTokens,
+    toolResults,
+    totalTokens: userTokens + assistantTokens + toolTokens,
+  };
+}
+
+// ── 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');
+}
+
+function formatFullContextBreakdown(context: ICommandHostContext): ICommandResult {
+  const state = readCommandContextState(context);
+  const autoCompactThreshold = readAutoCompactThreshold(context);
+  const autoCompactThresholdSource = readAutoCompactThresholdSource(context);
+  const history = context.getSession().getFullHistory();
+  const analysis = analyzeHistory(history);
+  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 systemTokens = 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 =
+    analysis.turnCount === 0
+      ? 'Conversation history — 0 turns'
+      : `Conversation history — ${analysis.turnCount} turn${analysis.turnCount !== 1 ? 's' : ''} | ~${analysis.totalTokens.toLocaleString()} tokens`;
+
+  const toolResultLines = analysis.toolResults.map(
+    (t) =>
+      `${t.toolName}${t.displayArg ? `: ${t.displayArg}` : ''} — ~${t.tokens.toLocaleString()} tokens`,
+  );
+
+  const conversationLines: string[] =
+    analysis.turnCount === 0
+      ? []
+      : [
+          `User (${analysis.userCount}): ~${analysis.userTokens.toLocaleString()} tokens`,
+          `Assistant (${analysis.assistantCount}): ~${analysis.assistantTokens.toLocaleString()} tokens`,
+          analysis.toolResults.length > 0
+            ? [
+                `Tool results (${analysis.toolResults.length}):`,
+                ...toolResultLines.map((l) => `  ${l}`),
+              ].join('\n')
+            : `Tool results (0): (none)`,
+        ];
+
+  const convSection =
+    analysis.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)',
+      systemTokens,
+      systemRefs.map(formatContextReferenceLine),
+    ),
+    '',
+    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: analysis.turnCount, toolResults: analysis.toolResults },
+    },
+  };
+}

package/src/exit/exit-command-module.ts

@@ -4,6 +4,7 @@ import { executeExitCommand } from './exit-command.js';
 
 import type {
   ICommand,
+  ICommandInteractionHint,
   ICommandModule,
   ICommandSource,
   ISystemCommand,
@@ -41,10 +42,15 @@ export class ExitCommandSource implements ICommandSource {
   }
 }
 
+const EXIT_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
+  exit: { type: 'confirm', message: 'Exit the session?' },
+};
+
 export function createExitCommandModule(): ICommandModule {
   return {
     name: 'agent-command-exit',
     commandSources: [new ExitCommandSource()],
     systemCommands: [createExitSystemCommand()],
+    interactionHints: EXIT_INTERACTION_HINTS,
   };
 }

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

@@ -19,6 +19,7 @@ function createCommandSessionRuntime(): ICommandSessionRuntime {
     getMessageCount: () => 0,
     getSessionAllowedTools: () => [],
     getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
   };
 }
 

package/src/help/__tests__/help-command.test.ts

@@ -22,6 +22,7 @@ function createCommandSessionRuntime(): ICommandSessionRuntime {
     getMessageCount: () => 0,
     getSessionAllowedTools: () => [],
     getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
   };
 }
 

package/src/language/language-command-module.ts

@@ -8,6 +8,7 @@ import { executeLanguageCommand } from './language-command.js';
 
 import type {
   ICommand,
+  ICommandInteractionHint,
   ICommandModule,
   ICommandSource,
   ISystemCommand,
@@ -49,10 +50,23 @@ export class LanguageCommandSource implements ICommandSource {
   }
 }
 
+const LANGUAGE_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
+  language: {
+    type: 'pick',
+    getItems: () =>
+      buildLanguageCommandSubcommands().map((sub) => ({
+        label: `${sub.name}  ${sub.description ?? ''}`.trimEnd(),
+        value: sub.name,
+        description: sub.description,
+      })),
+  },
+};
+
 export function createLanguageCommandModule(): ICommandModule {
   return {
     name: 'agent-command-language',
     commandSources: [new LanguageCommandSource()],
     systemCommands: [createLanguageSystemCommand()],
+    interactionHints: LANGUAGE_INTERACTION_HINTS,
   };
 }

package/src/mode/mode-command-module.ts

@@ -8,6 +8,7 @@ import { executeModeCommand } from './mode-command.js';
 
 import type {
   ICommand,
+  ICommandInteractionHint,
   ICommandModule,
   ICommandSource,
   ISystemCommand,
@@ -49,10 +50,23 @@ export class ModeCommandSource implements ICommandSource {
   }
 }
 
+const MODE_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
+  mode: {
+    type: 'pick',
+    getItems: () =>
+      buildPermissionModeSubcommands().map((sub) => ({
+        label: sub.name,
+        value: sub.name,
+        description: sub.description,
+      })),
+  },
+};
+
 export function createModeCommandModule(): ICommandModule {
   return {
     name: 'agent-command-mode',
     commandSources: [new ModeCommandSource()],
     systemCommands: [createModeSystemCommand()],
+    interactionHints: MODE_INTERACTION_HINTS,
   };
 }

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

@@ -40,6 +40,7 @@ function createCommandSessionRuntime(): ICommandSessionRuntime {
     getMessageCount: () => 0,
     getSessionAllowedTools: () => [],
     getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
   };
 }
 

package/src/provider/provider-command-module.ts

@@ -2,6 +2,7 @@ import { executeProviderCommand } from './provider-command-execution.js';
 
 import type {
   ICommand,
+  ICommandInteractionHint,
   ICommandModule as TCommandModule,
   ICommandSource,
   IProviderCommandModuleOptions,
@@ -57,6 +58,18 @@ function createProviderSystemCommand(options: IProviderCommandModuleOptions): TS
   };
 }
 
+const PROVIDER_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
+  provider: {
+    type: 'pick',
+    getItems: () =>
+      buildProviderSubcommands().map((sub) => ({
+        label: sub.name,
+        value: sub.name,
+        description: sub.description,
+      })),
+  },
+};
+
 export function createProviderCommandModule(
   options: IProviderCommandModuleOptions,
 ): TCommandModule {
@@ -64,5 +77,6 @@ export function createProviderCommandModule(
     name: 'agent-command-provider',
     commandSources: [new ProviderCommandSource()],
     systemCommands: [createProviderSystemCommand(options)],
+    interactionHints: PROVIDER_INTERACTION_HINTS,
   };
 }

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

@@ -19,6 +19,7 @@ function createRuntime(): ICommandSessionRuntime {
     getMessageCount: () => 5,
     getSessionAllowedTools: () => [],
     getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
   };
 }
 

package/src/session/session-command-module.ts

@@ -16,6 +16,7 @@ import {
 
 import type {
   ICommand,
+  ICommandInteractionHint,
   ICommandModule,
   ICommandSource,
   ISystemCommand,
@@ -155,6 +156,10 @@ export class SessionCommandSource implements ICommandSource {
   }
 }
 
+const SESSION_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
+  clear: { type: 'confirm', message: 'Clear conversation history?' },
+};
+
 export function createSessionCommandModule(): ICommandModule {
   return {
     name: 'agent-command-session',
@@ -166,5 +171,6 @@ export function createSessionCommandModule(): ICommandModule {
       createCostSystemCommand(),
       createValidateSessionSystemCommand(),
     ],
+    interactionHints: SESSION_INTERACTION_HINTS,
   };
 }