@robota-sdk/agent-command 3.0.0-beta.67 → 3.0.0-beta.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-command",
-  "version": "3.0.0-beta.67",
+  "version": "3.0.0-beta.69",
   "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.67",
-    "@robota-sdk/agent-framework": "3.0.0-beta.67"
+    "@robota-sdk/agent-core": "3.0.0-beta.69",
+    "@robota-sdk/agent-framework": "3.0.0-beta.69"
   },
   "devDependencies": {
     "@types/node": "^22.14.0",

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

@@ -20,8 +20,9 @@ const AFTER_CONTEXT: TContextWindowState = {
   remainingPercentage: 65,
 };
 
-function createRuntime(): ICommandSessionRuntime {
+function createRuntime(beforeCount = 10, afterCount = 3): ICommandSessionRuntime {
   let mode: TPermissionMode = 'default';
+  const getMessageCount = vi.fn().mockReturnValueOnce(beforeCount).mockReturnValue(afterCount);
   return {
     clearHistory: vi.fn(),
     compact: vi.fn().mockResolvedValue(undefined),
@@ -31,7 +32,7 @@ function createRuntime(): ICommandSessionRuntime {
       mode = nextMode;
     },
     getSessionId: () => 'session_1',
-    getMessageCount: () => 1,
+    getMessageCount,
     getSessionAllowedTools: () => [],
     getAutoCompactThreshold: () => 0.835,
   };
@@ -104,6 +105,7 @@ describe('createCompactCommandModule', () => {
         modelInvocable: true,
         argumentHint: '[instructions]',
         safety: 'write',
+        requiresPermission: false,
       },
     ]);
   });
@@ -117,8 +119,15 @@ describe('createCompactCommandModule', () => {
     const result = await executor.execute('compact', context, ' focus on tests ');
 
     expect(result?.success).toBe(true);
-    expect(result?.message).toBe('Context compacted: 80% -> 35%');
-    expect(result?.data).toEqual({ before: 80, after: 35 });
+    expect(result?.message).toBe(
+      'Context compacted.\n  Removed messages: 7 (70% of total)\n  Context: 80% → 35%',
+    );
+    expect(result?.data).toEqual({
+      before: BEFORE_CONTEXT,
+      after: AFTER_CONTEXT,
+      beforeMessageCount: 10,
+      afterMessageCount: 3,
+    });
     expect(context.compactContext).toHaveBeenCalledWith('focus on tests');
   });
 

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

@@ -16,6 +16,7 @@ export function createCompactCommandEntry(): ICommand {
     modelInvocable: true,
     argumentHint: '[instructions]',
     safety: 'write',
+    example: '/compact Summarize the current context',
   };
 }
 
@@ -25,6 +26,7 @@ function createCompactSystemCommand(): ISystemCommand {
     name: entry.name,
     displayName: entry.displayName,
     description: entry.description,
+    example: entry.example,
     requiresPermission: false,
     userInvocable: true,
     modelInvocable: entry.modelInvocable,

package/src/compact/compact-command.ts

@@ -12,11 +12,18 @@ export async function executeCompactCommand(
   args: string,
 ): Promise<ICommandResult> {
   const result = await compactCommandContext(context, parseInstructions(args));
-  const before = result.before.usedPercentage;
-  const after = result.after.usedPercentage;
+  const { before, after, beforeMessageCount, afterMessageCount } = result;
+  const removedMessages = beforeMessageCount - afterMessageCount;
+  const removedPercent =
+    beforeMessageCount > 0 ? Math.round((removedMessages / beforeMessageCount) * 100) : 0;
+  const message = [
+    'Context compacted.',
+    `  Removed messages: ${removedMessages} (${removedPercent}% of total)`,
+    `  Context: ${Math.round(before.usedPercentage)}% → ${Math.round(after.usedPercentage)}%`,
+  ].join('\n');
   return {
-    message: `Context compacted: ${Math.round(before)}% -> ${Math.round(after)}%`,
+    message,
     success: true,
-    data: { before, after },
+    data: { before, after, beforeMessageCount, afterMessageCount },
   };
 }

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

@@ -45,6 +45,18 @@ const PROMPT_REFERENCE: IContextReferenceItem = {
   lastUsedAt: '2026-05-05T00:00:01.000Z',
 };
 
+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 }): ICommandSessionRuntime {
   let mode: TPermissionMode = 'default';
   return {
@@ -291,4 +303,34 @@ 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] 1,024 B');
+    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 no context references message when only system refs are absent', async () => {
+    const context = createCommandHostContext();
+
+    const result = await createExecutor().execute('context', context, 'list');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('No context references.');
+  });
 });

package/src/default/default-command-modules.ts

@@ -7,7 +7,6 @@ import { createHelpCommandModule } from '../help/index.js';
 import { createLanguageCommandModule } from '../language/index.js';
 import { createMemoryCommandModule } from '../memory/index.js';
 import { createModeCommandModule } from '../mode/index.js';
-import { createModelCommandModule } from '../model/index.js';
 import { createPermissionsCommandModule } from '../permissions/index.js';
 import { createPluginCommandModule } from '../plugin/index.js';
 import { createProviderCommandModule } from '../provider/index.js';
@@ -37,10 +36,6 @@ export function createDefaultCommandModules({
     createSkillsCommandModule({ cwd }),
     createHelpCommandModule(),
     createAgentCommandModule(),
-    createModelCommandModule({
-      providerDefinitions,
-      settings: { readMergedSettings: () => providerSettingsAdapter.readMergedSettings() },
-    }),
     createPermissionsCommandModule(),
     createModeCommandModule(),
     createLanguageCommandModule(),

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

@@ -0,0 +1,119 @@
+import type {
+  ICommandHostContext,
+  ICommandListEntry,
+  ICommandSessionRuntime,
+} from '@robota-sdk/agent-framework';
+import { formatCommandHelpMessage } from '@robota-sdk/agent-framework';
+import { describe, expect, it } from 'vitest';
+
+function createCommandSessionRuntime(): ICommandSessionRuntime {
+  return {
+    clearHistory: () => undefined,
+    compact: async () => undefined,
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getPermissionMode: () => 'default',
+    setPermissionMode: () => undefined,
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 0,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => false,
+  };
+}
+
+function createCheckpoint() {
+  return {
+    id: 'checkpoint_1',
+    sessionId: 'session_1',
+    sequence: 1,
+    prompt: 'prompt',
+    createdAt: '2026-05-25T00:00:00.000Z',
+    fileCount: 0,
+  };
+}
+
+function buildContext(commands: ICommandListEntry[]): ICommandHostContext {
+  const checkpoint = createCheckpoint();
+  return {
+    getSession: () => createCommandSessionRuntime(),
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getAutoCompactThreshold: () => 0.8,
+    compactContext: async () => undefined,
+    getCwd: () => '/workspace',
+    listCommands: () => commands,
+    listEditCheckpoints: () => [],
+    restoreEditCheckpoint: async () => ({
+      target: checkpoint,
+      restoredCheckpointCount: 0,
+      restoredFileCount: 0,
+      removedCheckpointCount: 0,
+    }),
+    rollbackEditCheckpoint: async () => ({
+      target: checkpoint,
+      restoredCheckpointCount: 0,
+      restoredFileCount: 0,
+      removedCheckpointCount: 0,
+    }),
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: () => undefined,
+    listBackgroundTasks: () => [],
+    readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+    cancelBackgroundTask: async () => undefined,
+    closeBackgroundTask: async () => undefined,
+  };
+}
+
+describe('formatCommandHelpMessage — example field', () => {
+  it('TC-01: includes Example line for compact command', () => {
+    const context = buildContext([
+      {
+        name: 'compact',
+        displayName: 'Compact Context',
+        description: 'Compress context window',
+        example: '/compact Summarize the current context',
+      },
+    ]);
+
+    const output = formatCommandHelpMessage(context);
+
+    expect(output).toContain('Example: /compact Summarize the current context');
+  });
+
+  it('TC-02: includes Example line for provider command', () => {
+    const context = buildContext([
+      {
+        name: 'provider',
+        displayName: 'Provider Setup',
+        description: 'Manage provider profiles',
+        example: '/provider switch production',
+      },
+    ]);
+
+    const output = formatCommandHelpMessage(context);
+
+    expect(output).toContain('Example: /provider switch production');
+  });
+
+  it('TC-03: omits Example line for commands without example', () => {
+    const context = buildContext([
+      {
+        name: 'help',
+        displayName: 'Help',
+        description: 'Show available commands',
+      },
+    ]);
+
+    const output = formatCommandHelpMessage(context);
+
+    expect(output).not.toContain('Example:');
+  });
+});

package/src/index.ts

@@ -8,7 +8,6 @@ export * from './help/index.js';
 export * from './language/index.js';
 export * from './memory/index.js';
 export * from './mode/index.js';
-export * from './model/index.js';
 export * from './permissions/index.js';
 export * from './plugin/index.js';
 export * from './provider/index.js';

package/src/provider/__tests__/org-policy.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import type {
+  ICommandHostContext,
+  IOrgPolicy,
+  IProviderCommandSettingsAdapter,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+import { createProviderCommandModule } from '../provider-command-module.js';
+
+const providerDefinitions: readonly IProviderDefinition[] = [
+  {
+    type: 'anthropic',
+    displayName: 'Anthropic',
+    defaults: { model: 'claude-sonnet-4-6', apiKey: '$ENV:ANTHROPIC_API_KEY' },
+    setupSteps: [
+      { key: 'apiKey', title: 'Anthropic API key', masked: true },
+      { key: 'model', title: 'Anthropic model', defaultValue: 'claude-sonnet-4-6' },
+    ],
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+  {
+    type: 'openai',
+    displayName: 'OpenAI',
+    defaults: { model: 'gpt-4o', apiKey: '$ENV:OPENAI_API_KEY' },
+    setupSteps: [
+      { key: 'apiKey', title: 'OpenAI API key', masked: true },
+      { key: 'model', title: 'OpenAI model', defaultValue: 'gpt-4o' },
+    ],
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+];
+
+function createSettingsAdapter(
+  merged: TProviderSettingsDocument,
+  target: TProviderSettingsDocument = {},
+): { adapter: IProviderCommandSettingsAdapter } {
+  let writable = target;
+  return {
+    adapter: {
+      readMergedSettings: () => merged,
+      readTargetSettings: () => writable,
+      writeTargetSettings: (next) => {
+        writable = next;
+      },
+    },
+  };
+}
+
+function createExecutor(
+  adapter: IProviderCommandSettingsAdapter,
+  orgPolicy?: IOrgPolicy,
+): SystemCommandExecutor {
+  const module = createProviderCommandModule({ providerDefinitions, settings: adapter, orgPolicy });
+  return new SystemCommandExecutor([...(module.systemCommands ?? [])]);
+}
+
+const session = {} as ICommandHostContext;
+
+describe('org policy enforcement in provider commands', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+  it('blocks /provider switch when target is not in allowedProviders', async () => {
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-sonnet-4-6' },
+        openai: { type: 'openai', model: 'gpt-4o' },
+      },
+    });
+    const orgPolicy: IOrgPolicy = {
+      allowedProviders: ['anthropic'],
+      adminContact: 'admin@example.com',
+    };
+
+    const result = await createExecutor(adapter, orgPolicy).execute(
+      'provider',
+      session,
+      'switch openai',
+    );
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('"openai" is not allowed');
+    expect(result?.message).toContain('admin@example.com');
+    expect(result?.effects).toBeUndefined();
+  });
+
+  it('allows /provider switch when target is in allowedProviders', async () => {
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-sonnet-4-6' },
+        openai: { type: 'openai', model: 'gpt-4o' },
+      },
+    });
+    const orgPolicy: IOrgPolicy = { allowedProviders: ['anthropic', 'openai'] };
+
+    const result = await createExecutor(adapter, orgPolicy).execute(
+      'provider',
+      session,
+      'switch openai',
+    );
+
+    expect(result?.success).toBe(true);
+    expect(result?.effects).toEqual([
+      { type: 'provider-hot-swap-requested', profileName: 'openai' },
+    ]);
+  });
+
+  it('rejects plaintext API key during edit when requireApiKeyFromEnv is true', async () => {
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: {
+          type: 'anthropic',
+          model: 'claude-sonnet-4-6',
+          apiKey: 'sk-existing-key',
+        },
+      },
+    });
+    const orgPolicy: IOrgPolicy = { requireApiKeyFromEnv: true, adminContact: 'sec@example.com' };
+
+    const listed = await createExecutor(adapter, orgPolicy).execute('provider', session, 'list');
+    const selected = await listed?.interaction?.submit('anthropic');
+    const editRequested = await selected?.interaction?.submit('edit');
+    // Anthropic has 2 setup steps: apiKey then model
+    const modelPrompt = await editRequested?.interaction?.submit('sk-plaintext-key');
+    const completed = await modelPrompt?.interaction?.submit('claude-sonnet-4-6');
+
+    expect(completed?.success).toBe(false);
+    expect(completed?.message).toContain('environment variable references');
+    expect(completed?.message).toContain('sec@example.com');
+  });
+
+  it('allows env-ref API key during edit when requireApiKeyFromEnv is true', async () => {
+    vi.stubEnv('ORG_TEST_KEY', 'sk-test-resolved-value');
+    const { adapter } = createSettingsAdapter({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: {
+          type: 'anthropic',
+          model: 'claude-sonnet-4-6',
+          apiKey: 'sk-existing-key',
+        },
+      },
+    });
+    const orgPolicy: IOrgPolicy = { requireApiKeyFromEnv: true };
+
+    const listed = await createExecutor(adapter, orgPolicy).execute('provider', session, 'list');
+    const selected = await listed?.interaction?.submit('anthropic');
+    const editRequested = await selected?.interaction?.submit('edit');
+    const modelPrompt = await editRequested?.interaction?.submit('$ENV:ORG_TEST_KEY');
+    const completed = await modelPrompt?.interaction?.submit('claude-opus-4-5');
+
+    expect(completed?.success).toBe(true);
+  });
+});

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

@@ -103,7 +103,7 @@ describe('createProviderCommandModule', () => {
 
     expect(module.name).toBe('agent-command-provider');
     expect(commands.map((command) => command.name)).toEqual(['provider']);
-    expect(commands[0]?.subcommands?.map((command) => command.name)).toContain('use');
+    expect(commands[0]?.subcommands?.map((command) => command.name)).toContain('switch');
     expect(module.systemCommands?.map((command) => command.name)).toEqual(['provider']);
   });
 
@@ -146,7 +146,7 @@ describe('createProviderCommandModule', () => {
     });
   });
 
-  it('confirms provider switch through a generic command interaction', async () => {
+  it('switches provider immediately via /provider switch without confirmation dialog', async () => {
     const { adapter, readTarget } = createSettingsAdapter(
       {
         currentProvider: 'anthropic',
@@ -158,24 +158,19 @@ describe('createProviderCommandModule', () => {
       {},
     );
 
-    const result = await createExecutor(adapter).execute('provider', session, 'use openai');
-    const submitted = await result?.interaction?.submit('yes');
+    const result = await createExecutor(adapter).execute('provider', session, 'switch openai');
 
-    expect(result?.interaction?.prompt).toMatchObject({
-      kind: 'choice',
-      title: 'Change provider to openai? This will restart the session.',
-    });
+    expect(result?.interaction).toBeUndefined();
+    expect(result?.message).toBe(
+      'Switched to openai (supergemma4-26b-uncensored-v2). History preserved.',
+    );
     expect(readTarget().currentProvider).toBe('openai');
-    expect(submitted?.effects).toEqual([
-      {
-        type: 'session-restart-requested',
-        reason: 'other',
-        message: 'Provider change restart',
-      },
+    expect(result?.effects).toEqual([
+      { type: 'provider-hot-swap-requested', profileName: 'openai' },
     ]);
   });
 
-  it('switches from the provider profile action menu through the same restart interaction', async () => {
+  it('switches from the provider profile action menu immediately without confirmation', async () => {
     const { adapter, readTarget } = createSettingsAdapter(
       {
         currentProvider: 'anthropic',
@@ -190,16 +185,14 @@ describe('createProviderCommandModule', () => {
     const listed = await createExecutor(adapter).execute('provider', session, 'list');
     const selected = await listed?.interaction?.submit('openai');
     const switchRequested = await selected?.interaction?.submit('switch');
-    const submitted = await switchRequested?.interaction?.submit('yes');
 
-    expect(switchRequested?.message).toBe('Provider change requested: openai');
+    expect(switchRequested?.message).toBe(
+      'Switched to openai (supergemma4-26b-uncensored-v2). History preserved.',
+    );
+    expect(switchRequested?.interaction).toBeUndefined();
     expect(readTarget().currentProvider).toBe('openai');
-    expect(submitted?.effects).toEqual([
-      {
-        type: 'session-restart-requested',
-        reason: 'other',
-        message: 'Provider change restart',
-      },
+    expect(switchRequested?.effects).toEqual([
+      { type: 'provider-hot-swap-requested', profileName: 'openai' },
     ]);
   });
 
@@ -241,13 +234,9 @@ describe('createProviderCommandModule', () => {
         },
       },
     });
-    expect(completed?.message).toBe('Provider anthropic updated. Restarting...');
+    expect(completed?.message).toBe('Provider anthropic updated. Switching...');
     expect(completed?.effects).toEqual([
-      {
-        type: 'session-restart-requested',
-        reason: 'other',
-        message: 'Provider edit restart',
-      },
+      { type: 'provider-hot-swap-requested', profileName: 'anthropic' },
     ]);
   });
 

package/src/provider/__tests__/provider-setup-flow.test.ts

@@ -82,8 +82,8 @@ describe('provider setup flow', () => {
     expect(formatProviderSetupSelectionPrompt(providerDefinitions)).toBe(
       [
         '  Select provider:',
-        '    1. OpenAI (openai) - Use OpenAI Responses API',
-        '    2. Anthropic (anthropic) - Use Claude models through Anthropic',
+        '    1. OpenAI (openai) — Use OpenAI Responses API',
+        '    2. Anthropic (anthropic) — Use Claude models through Anthropic',
         '  Provider [1-2] (default: 1): ',
       ].join('\n'),
     );

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

@@ -33,7 +33,7 @@ export async function executeProviderCommand(
       success: true,
     };
   }
-  if (subcommand === 'use') {
+  if (subcommand === 'switch') {
     return buildProviderSwitch(settings.providers, profileArg, options);
   }
   if (subcommand === 'test') {
@@ -49,7 +49,7 @@ export async function executeProviderCommand(
   }
 
   return {
-    message: 'Usage: provider [current|list|use <profile>|add <type>|test [profile]]',
+    message: 'Usage: provider [current|list|switch <profile>|add <type>|test [profile]]',
     success: false,
   };
 }

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

@@ -14,7 +14,7 @@ function buildProviderSubcommands(): ICommand[] {
   return [
     { name: 'current', description: 'Show current provider', source: 'provider' },
     { name: 'list', description: 'List provider profiles', source: 'provider' },
-    { name: 'use', description: 'Switch provider profile', source: 'provider' },
+    { name: 'switch', description: 'Hot-swap to another provider profile', source: 'provider' },
     { name: 'add', description: 'Configure a provider profile', source: 'provider' },
     { name: 'test', description: 'Test provider profile', source: 'provider' },
   ];
@@ -27,8 +27,9 @@ export function createProviderCommandEntry(): ICommand {
     description: 'Manage provider profiles',
     source: 'provider',
     modelInvocable: false,
-    argumentHint: 'current | list | use <profile> | add [type] | test [profile]',
+    argumentHint: 'current | list | switch <profile> | add [type] | test [profile]',
     subcommands: buildProviderSubcommands(),
+    example: '/provider switch production',
   };
 }
 
@@ -46,6 +47,7 @@ function createProviderSystemCommand(options: IProviderCommandModuleOptions): TS
     name: entry.name,
     displayName: entry.displayName,
     description: entry.description,
+    example: entry.example,
     requiresPermission: false,
     userInvocable: true,
     modelInvocable: false,