@robota-sdk/agent-command 3.0.0-beta.100

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

@@ -0,0 +1,230 @@
+import { describe, expect, it, vi } from 'vitest';
+import type {
+  ICommandHostContext,
+  IEditCheckpointRestoreResult,
+} from '@robota-sdk/agent-framework';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createModeCommandModule } from '../mode-command-module.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+type TPermissionModeName = 'plan' | 'default' | 'acceptEdits' | 'bypassPermissions';
+type TSetPermissionModeSpy = ReturnType<typeof vi.fn<(nextMode: TPermissionModeName) => void>>;
+
+function createCheckpointResult(): IEditCheckpointRestoreResult {
+  return {
+    target: {
+      id: 'checkpoint_1',
+      sessionId: 'session_1',
+      sequence: 1,
+      prompt: 'edit files',
+      createdAt: '2026-05-03T00:00:00.000Z',
+      fileCount: 1,
+    },
+    restoredCheckpointCount: 0,
+    restoredFileCount: 0,
+    removedCheckpointCount: 0,
+  };
+}
+
+function createCommandHostContext(): ReturnType<typeof createTestCommandHost> & {
+  setPermissionMode: TSetPermissionModeSpy;
+} {
+  let mode: TPermissionModeName = 'default';
+  const setPermissionMode = vi.fn((nextMode: TPermissionModeName) => {
+    mode = nextMode;
+  });
+
+  return {
+    ...createTestCommandHost({
+      overrides: {
+        getSession: () => {
+          throw new Error('mode command should use the permission mode adapter');
+        },
+        getCommandHostAdapters: () => ({
+          permissionMode: {
+            getPermissionMode: () => mode,
+            setPermissionMode,
+            listSessionAllowedTools: () => [],
+            getPermissionRules: () => ({ allow: [], deny: [], ask: [] }),
+            listRecentDenials: () => [],
+            retryDenial: () => undefined,
+          },
+        }),
+        getContextState: () => ({
+          usedTokens: 0,
+          maxTokens: 1,
+          usedPercentage: 0,
+          remainingPercentage: 100,
+        }),
+        getAutoCompactThreshold: () => 0.835,
+        compactContext: async () => undefined,
+        getCwd: () => '/workspace',
+        listEditCheckpoints: () => [],
+        restoreEditCheckpoint: async () => createCheckpointResult(),
+        rollbackEditCheckpoint: async () => createCheckpointResult(),
+        getUsedMemoryReferences: () => [],
+        recordMemoryEvent: () => undefined,
+        listBackgroundTasks: () => [],
+        readBackgroundTaskLog: async () => ({ taskId: 'task_1', lines: [] }),
+        cancelBackgroundTask: async () => undefined,
+        closeBackgroundTask: async () => undefined,
+      },
+    }),
+    setPermissionMode,
+  };
+}
+
+describe('createModeCommandModule', () => {
+  it('provides mode metadata and executable command from one module owner', () => {
+    const module = createModeCommandModule();
+    const command = module.systemCommands?.[0];
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+
+    expect(module.name).toBe('agent-command-mode');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'mode',
+        description: 'Show/change permission mode',
+        argumentHint: 'plan | default | acceptEdits | bypassPermissions | auto',
+        source: 'mode',
+        modelInvocable: false,
+      }),
+    );
+    expect(entry?.subcommands?.map((subcommand) => subcommand.name)).toEqual([
+      'plan',
+      'default',
+      'acceptEdits',
+      'bypassPermissions',
+      'auto',
+    ]);
+    // #3282 §2: a plain label beside every description, so a client never shows the raw id.
+    expect(entry?.subcommands?.map((subcommand) => subcommand.displayName)).toEqual([
+      'Plan only',
+      'Ask first',
+      'Accept edits',
+      'Skip all checks',
+      'Auto',
+    ]);
+    expect(entry?.subcommands?.every((subcommand) => subcommand.description.length > 0)).toBe(true);
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'mode',
+        description: 'Show/change permission mode',
+        argumentHint: 'plan | default | acceptEdits | bypassPermissions | auto',
+        lifecycle: 'inline',
+        modelInvocable: false,
+      }),
+    );
+    expect(command?.subcommands).toEqual(entry?.subcommands);
+  });
+
+  it('reports the current permission mode through the SDK command adapter', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModeCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('mode', createCommandHostContext(), '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Current mode: default');
+    expect(result?.data?.mode).toBe('default');
+  });
+
+  it('updates valid permission modes through the SDK command adapter', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModeCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+
+    const result = await executor.execute('mode', context, 'plan');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Permission mode set to: plan');
+    expect(result?.data?.mode).toBe('plan');
+    expect(context.setPermissionMode).toHaveBeenCalledWith('plan');
+  });
+
+  it('rejects invalid permission modes without writing state', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModeCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+
+    const result = await executor.execute('mode', context, 'invalid');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toBe(
+      'Invalid mode. Valid: plan | default | acceptEdits | bypassPermissions | auto',
+    );
+    expect(context.setPermissionMode).not.toHaveBeenCalled();
+  });
+
+  it('#3282 §2: the picker shows plain labels with their descriptions, never a raw id', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModeCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+    const ask = vi.fn().mockResolvedValue({ type: 'answer', values: ['plan'] });
+    const contextWithAsk = createTestCommandHost({
+      overrides: { ...context, getUserInteraction: () => ({ ask }) },
+    });
+
+    await executor.execute('mode', contextWithAsk, '');
+
+    expect(ask).toHaveBeenCalledTimes(1);
+    const request = ask.mock.calls[0]![0];
+    expect(request.options).toEqual([
+      { value: 'plan', label: 'Plan only', description: 'Plan only, no execution' },
+      { value: 'default', label: 'Ask first', description: 'Ask before risky actions' },
+      { value: 'acceptEdits', label: 'Accept edits', description: 'Auto-approve file edits' },
+      {
+        value: 'bypassPermissions',
+        label: 'Skip all checks',
+        description: 'Skip all permission checks',
+      },
+      {
+        value: 'auto',
+        label: 'Auto',
+        description: 'A model classifier approves or blocks risky actions',
+      },
+    ]);
+  });
+
+  it('asks the user to pick a mode when no arg is given and a renderer is attached (CMD-004)', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModeCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+    const contextWithAsk = createTestCommandHost({
+      overrides: {
+        ...context,
+        getUserInteraction: () => ({ ask: async () => ({ type: 'answer', values: ['plan'] }) }),
+      },
+    });
+
+    const result = await executor.execute('mode', contextWithAsk, '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Permission mode set to: plan');
+    expect(context.setPermissionMode).toHaveBeenCalledWith('plan');
+  });
+
+  it('reports the current mode when the user cancels the pick (CMD-004)', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModeCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+    const contextWithAsk = createTestCommandHost({
+      overrides: {
+        ...context,
+        getUserInteraction: () => ({ ask: async () => ({ type: 'cancelled' }) }),
+      },
+    });
+
+    const result = await executor.execute('mode', contextWithAsk, '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Current mode: default');
+    expect(context.setPermissionMode).not.toHaveBeenCalled();
+  });
+});

package/src/mode/index.ts

@@ -0,0 +1,6 @@
+export {
+  createModeCommandEntry,
+  createModeCommandModule,
+  ModeCommandSource,
+} from './mode-command-module.js';
+export { executeModeCommand } from './mode-command.js';

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

@@ -0,0 +1,55 @@
+import {
+  buildPermissionModeSubcommands,
+  PERMISSION_MODE_ARGUMENT_HINT,
+  PERMISSION_MODE_COMMAND_DESCRIPTION,
+} from '@robota-sdk/agent-framework';
+
+import { executeModeCommand } from './mode-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createModeCommandEntry(): ICommand {
+  return {
+    name: 'mode',
+    displayName: 'Interaction Mode',
+    description: PERMISSION_MODE_COMMAND_DESCRIPTION,
+    source: 'mode',
+    argumentHint: PERMISSION_MODE_ARGUMENT_HINT,
+    subcommands: buildPermissionModeSubcommands('mode'),
+    // User-only: changes the permission mode; permission widening is the user's.
+    modelInvocable: false,
+  };
+}
+
+function createModeSystemCommand(): ISystemCommand {
+  const entry = createModeCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    argumentHint: entry.argumentHint,
+    subcommands: entry.subcommands,
+    lifecycle: 'inline',
+    execute: executeModeCommand,
+  };
+}
+
+export class ModeCommandSource implements ICommandSource {
+  readonly name = 'mode';
+
+  getCommands(): ICommand[] {
+    return [createModeCommandEntry()];
+  }
+}
+
+export function createModeCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-mode',
+    commandSources: [new ModeCommandSource()],
+    systemCommands: [createModeSystemCommand()],
+  };
+}

package/src/mode/mode-command.ts

@@ -0,0 +1,67 @@
+import { selectAction } from '@robota-sdk/agent-core';
+import {
+  buildPermissionModeSubcommands,
+  formatInvalidPermissionModeMessage,
+  isPermissionMode,
+  parsePermissionModeArgument,
+  readCommandPermissionMode,
+} from '@robota-sdk/agent-framework';
+
+import { tryWritePermissionMode } from '../permissions/permissions-command.js';
+
+import type {
+  ICommandHostAdapterAccess,
+  ICommandHostSessionAccess,
+  ICommandHostUserInteraction,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+/**
+ * Ask the user to pick a permission mode (CMD-004 inline ask). Returns the chosen mode name, or
+ * `undefined` when no interactive renderer is attached or the user cancelled — the caller then reports
+ * the current mode instead of changing it (never a silent guess).
+ */
+async function resolveModeViaAsk(
+  context: ICommandHostUserInteraction,
+): Promise<string | undefined> {
+  const ui = context.getUserInteraction();
+  if (!ui) return undefined;
+  const options = buildPermissionModeSubcommands().map((sub) => ({
+    value: sub.name,
+    label: sub.displayName ?? sub.name,
+    description: sub.description,
+  }));
+  const response = await ui.ask(selectAction('mode', 'Select interaction mode', options));
+  return response.type === 'answer' ? response.values[0] : undefined;
+}
+
+export async function executeModeCommand(
+  context: ICommandHostAdapterAccess & ICommandHostSessionAccess & ICommandHostUserInteraction,
+  args: string,
+): Promise<ICommandResult> {
+  let arg: string | undefined = parsePermissionModeArgument(args);
+
+  if (arg === undefined) {
+    arg = await resolveModeViaAsk(context);
+    if (arg === undefined) {
+      // No interactive answer — report the current mode without changing it.
+      const mode = readCommandPermissionMode(context);
+      return { message: `Current mode: ${mode}`, success: true, data: { mode } };
+    }
+  }
+
+  if (!isPermissionMode(arg)) {
+    return {
+      message: formatInvalidPermissionModeMessage(),
+      success: false,
+    };
+  }
+
+  const refused = tryWritePermissionMode(context, arg);
+  if (refused !== undefined) return refused;
+  return {
+    message: `Permission mode set to: ${arg}`,
+    success: true,
+    data: { mode: arg },
+  };
+}

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

@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createModelCommandEntry, createModelCommandModule } from '../model-command-module.js';
+
+import type { IProviderCommandModuleOptions, IProviderProfileSettings } from '@robota-sdk/agent-framework';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+
+function buildOptions(): IProviderCommandModuleOptions {
+  const providers: Record<string, IProviderProfileSettings> = {
+    anthropic: { type: 'anthropic', model: 'claude-sonnet-4-6' },
+  };
+  const definitions: readonly IProviderDefinition[] = [
+    {
+      type: 'anthropic',
+      displayName: 'Anthropic',
+      modelCatalog: { status: 'unavailable' },
+      createProvider: () => {
+        throw new Error('not used');
+      },
+    },
+  ];
+  const document = { currentProvider: 'anthropic', providers };
+  return {
+    providerDefinitions: definitions,
+    settings: {
+      readMergedSettings: () => document,
+      readTargetSettings: () => document,
+      writeTargetSettings: vi.fn(),
+    },
+  };
+}
+
+describe('createModelCommandModule (#3282 §2)', () => {
+  it('is user-only: never model-invocable', () => {
+    const entry = createModelCommandEntry();
+    expect(entry.modelInvocable).toBe(false);
+
+    const module = createModelCommandModule(buildOptions());
+    const command = module.systemCommands?.[0];
+    expect(command?.modelInvocable).toBe(false);
+  });
+
+  it('carries a model-facing description, name and argument hint', () => {
+    const entry = createModelCommandEntry();
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'model',
+        displayName: 'Model',
+        description: 'Show/change the model',
+        argumentHint: '[<id>]',
+        source: 'model',
+      }),
+    );
+  });
+
+  it('provides the metadata and the executable command from one module owner', () => {
+    const module = createModelCommandModule(buildOptions());
+    expect(module.name).toBe('agent-command-model');
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+    const command = module.systemCommands?.[0];
+    expect(entry?.name).toBe('model');
+    expect(command?.name).toBe('model');
+    expect(command?.lifecycle).toBe('inline');
+  });
+
+  it('runs "/model <id>" through the SDK command executor', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModelCommandModule(buildOptions()).systemCommands ?? []),
+    ]);
+    const host = createTestCommandHost({ session: { getModelId: () => 'claude-sonnet-4-6' } });
+
+    const result = await executor.execute('model', host, 'not-a-real-model');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toBe('Unknown model "not-a-real-model". Run /model to see the choices.');
+  });
+});