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

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

@@ -0,0 +1,273 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  ICommandHostContext,
+  IEditCheckpointRestoreResult,
+  IModelCommandModuleOptions,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createModelCommandModule } from '../model-command-module.js';
+
+type TTestProviderDefinition = NonNullable<
+  IModelCommandModuleOptions['providerDefinitions']
+>[number];
+
+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,
+  };
+}
+
+const commandHostContext: ICommandHostContext = {
+  getSession: () => {
+    throw new Error('model command should not read session runtime');
+  },
+  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,
+};
+
+const providerDefinitions: readonly TTestProviderDefinition[] = [
+  {
+    type: 'anthropic',
+    defaults: { model: 'claude-sonnet-4-6' },
+    modelCatalog: {
+      status: 'fallback',
+      lastVerifiedAt: '2026-05-04',
+      sourceUrl: 'https://platform.claude.com/docs/en/api/models/list',
+      entries: [
+        {
+          id: 'claude-sonnet-4-6',
+          displayName: 'Claude Sonnet 4.6',
+          contextWindow: 1_000_000,
+          lifecycle: 'active',
+        },
+      ],
+    },
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+  {
+    type: 'qwen',
+    defaults: { model: 'qwen-plus' },
+    modelCatalog: {
+      status: 'fallback',
+      lastVerifiedAt: '2026-05-04',
+      sourceUrl:
+        'https://www.alibabacloud.com/help/en/model-studio/compatibility-of-openai-with-dashscope',
+      entries: [
+        {
+          id: 'qwen-plus',
+          displayName: 'Qwen Plus',
+          lifecycle: 'active',
+        },
+        {
+          id: 'qwen-max',
+          displayName: 'Qwen Max',
+          lifecycle: 'active',
+        },
+      ],
+    },
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+  {
+    type: 'openai',
+    modelCatalog: {
+      status: 'unavailable',
+      sourceUrl: 'https://platform.openai.com/docs/api-reference/models/list',
+      message: 'OpenAI models should be discovered live.',
+    },
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+];
+
+const refreshableProviderDefinitions: readonly TTestProviderDefinition[] = [
+  {
+    type: 'openai',
+    modelCatalog: {
+      status: 'unavailable',
+      sourceUrl: 'https://platform.openai.com/docs/api-reference/models/list',
+      message: 'OpenAI models should be discovered live.',
+    },
+    refreshModelCatalog: async () => ({
+      status: 'live',
+      sourceUrl: 'https://platform.openai.com/docs/api-reference/models/list',
+      lastVerifiedAt: '2026-05-05T00:00:00.000Z',
+      entries: [{ id: 'gpt-5.1', displayName: 'gpt-5.1', lifecycle: 'active' }],
+    }),
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+];
+
+function createModelModuleForSettings(settings: TProviderSettingsDocument) {
+  return createModelCommandModule({
+    providerDefinitions,
+    settings: {
+      readMergedSettings: () => settings,
+    },
+  });
+}
+
+describe('createModelCommandModule', () => {
+  it('provides model metadata and executable command from one module owner', () => {
+    const module = createModelCommandModule();
+    const command = module.systemCommands?.[0];
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+
+    expect(module.name).toBe('agent-command-model');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'model',
+        description: 'Change AI model',
+        argumentHint: '<model-id>',
+        source: 'model',
+      }),
+    );
+    expect(entry?.subcommands?.map((subcommand) => subcommand.name)).toContain('claude-sonnet-4-6');
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'model',
+        description: 'Change AI model',
+        argumentHint: '<model-id>',
+        lifecycle: 'inline',
+      }),
+    );
+    expect(command?.subcommands).toEqual(entry?.subcommands);
+  });
+
+  it('deduplicates date-suffixed model variants in descriptor subcommands', () => {
+    const entry = createModelCommandModule().commandSources?.[0]?.getCommands()[0];
+    const names = entry?.subcommands?.map((subcommand) => subcommand.name) ?? [];
+
+    expect(names).toContain('claude-opus-4-6');
+    expect(names).toContain('claude-sonnet-4-6');
+    expect(names).toContain('claude-haiku-4-5');
+    expect(names).not.toContain('claude-haiku-4-5-20251001');
+    expect(names).not.toContain('claude-sonnet-4-5-20250929');
+    expect(names).not.toContain('claude-opus-4-5-20251101');
+  });
+
+  it('formats subcommand descriptions with human-readable names and context windows', () => {
+    const entry = createModelCommandModule().commandSources?.[0]?.getCommands()[0];
+    const subcommands = entry?.subcommands ?? [];
+
+    expect(
+      subcommands.find((subcommand) => subcommand.name === 'claude-opus-4-6')?.description,
+    ).toBe('Claude Opus 4.6 (1M)');
+    expect(
+      subcommands.find((subcommand) => subcommand.name === 'claude-haiku-4-5')?.description,
+    ).toBe('Claude Haiku 4.5 (200K)');
+  });
+
+  it('lists models for the effective active provider instead of Claude defaults', () => {
+    const entry = createModelModuleForSettings({
+      currentProvider: 'qwen',
+      providers: {
+        qwen: { type: 'qwen', model: 'qwen-plus' },
+        anthropic: { type: 'anthropic', model: 'claude-sonnet-4-6' },
+      },
+    }).commandSources?.[0]?.getCommands()[0];
+
+    const names = entry?.subcommands?.map((subcommand) => subcommand.name) ?? [];
+    expect(names).toEqual(['qwen-plus', 'qwen-max']);
+    expect(names).not.toContain('claude-sonnet-4-6');
+  });
+
+  it('keeps manual model input available when the active provider has no catalog', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModelModuleForSettings({
+        currentProvider: 'openai',
+        providers: {
+          openai: { type: 'openai', model: 'gpt-5.1' },
+        },
+      }).systemCommands ?? []),
+    ]);
+
+    const usage = await executor.execute('model', commandHostContext, '');
+    const manual = await executor.execute('model', commandHostContext, 'gpt-5.1');
+
+    expect(usage?.success).toBe(false);
+    expect(usage?.message).toContain('No model catalog available for provider openai');
+    expect(manual?.success).toBe(true);
+    expect(manual?.effects).toEqual([{ type: 'model-change-requested', modelId: 'gpt-5.1' }]);
+  });
+
+  it('surfaces refreshed catalog freshness when usage is requested', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModelCommandModule({
+        providerDefinitions: refreshableProviderDefinitions,
+        settings: {
+          readMergedSettings: () => ({
+            currentProvider: 'openai',
+            providers: {
+              openai: { type: 'openai', model: 'gpt-5.1', apiKey: 'sk-test' },
+            },
+          }),
+        },
+      }).systemCommands ?? []),
+    ]);
+
+    const usage = await executor.execute('model', commandHostContext, '');
+
+    expect(usage?.success).toBe(false);
+    expect(usage?.message).toContain('Catalog: live; 1 model(s)');
+    expect(usage?.message).toContain('verified 2026-05-05T00:00:00.000Z');
+  });
+
+  it('requests model changes through a typed command effect', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModelCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('model', commandHostContext, 'claude-sonnet-4-6');
+
+    expect(result?.success).toBe(true);
+    expect(result?.data?.modelId).toBe('claude-sonnet-4-6');
+    expect(result?.effects).toEqual([
+      { type: 'model-change-requested', modelId: 'claude-sonnet-4-6' },
+    ]);
+  });
+
+  it('shows usage when no model id is provided', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createModelCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('model', commandHostContext, '');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toBe('Usage: model <model-id>');
+  });
+});

package/src/model/index.ts

@@ -0,0 +1,6 @@
+export {
+  ModelCommandSource,
+  createModelCommandEntry,
+  createModelCommandModule,
+} from './model-command-module.js';
+export { executeModelCommand } from './model-command.js';

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

@@ -0,0 +1,68 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  IModelCommandModuleOptions,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import {
+  buildModelCommandSubcommands,
+  MODEL_COMMAND_ARGUMENT_HINT,
+  MODEL_COMMAND_DESCRIPTION,
+} from '@robota-sdk/agent-framework';
+import { executeModelCommand } from './model-command.js';
+
+export function createModelCommandEntry(options?: IModelCommandModuleOptions): ICommand {
+  return {
+    name: 'model',
+    displayName: 'Change Model',
+    description: MODEL_COMMAND_DESCRIPTION,
+    source: 'model',
+    argumentHint: MODEL_COMMAND_ARGUMENT_HINT,
+    subcommands: buildModelSubcommands(options),
+  };
+}
+
+function createModelSystemCommand(options?: IModelCommandModuleOptions): ISystemCommand {
+  const entry = createModelCommandEntry(options);
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: true,
+    userInvocable: true,
+    argumentHint: entry.argumentHint,
+    subcommands: entry.subcommands,
+    lifecycle: 'inline',
+    execute: (context, args) => executeModelCommand(context, args, options),
+  };
+}
+
+export class ModelCommandSource implements ICommandSource {
+  readonly name = 'model';
+
+  constructor(private readonly options?: IModelCommandModuleOptions) {}
+
+  getCommands(): ICommand[] {
+    return [createModelCommandEntry(this.options)];
+  }
+}
+
+export function createModelCommandModule(options?: IModelCommandModuleOptions): ICommandModule {
+  return {
+    name: 'agent-command-model',
+    commandSources: [new ModelCommandSource(options)],
+    systemCommands: [createModelSystemCommand(options)],
+  };
+}
+
+function buildModelSubcommands(options?: IModelCommandModuleOptions): ICommand[] {
+  if (options === undefined) {
+    return buildModelCommandSubcommands('model');
+  }
+  return buildModelCommandSubcommands({
+    source: 'model',
+    providerDefinitions: options.providerDefinitions,
+    settings: options.settings.readMergedSettings(),
+  });
+}

package/src/model/model-command.ts

@@ -0,0 +1,40 @@
+import type {
+  ICommandHostContext,
+  ICommandResult,
+  IModelCommandModuleOptions,
+} from '@robota-sdk/agent-framework';
+import { formatModelCommandUsageMessageAsync } from '@robota-sdk/agent-framework';
+
+function parseModelId(args: string): string | undefined {
+  const modelId = args.trim().split(/\s+/)[0];
+  return modelId !== undefined && modelId.length > 0 ? modelId : undefined;
+}
+
+export async function executeModelCommand(
+  _context: ICommandHostContext,
+  args: string,
+  options?: IModelCommandModuleOptions,
+): Promise<ICommandResult> {
+  const modelId = parseModelId(args);
+  if (modelId === undefined) {
+    return {
+      message: await formatModelCommandUsageMessageAsync({
+        ...(options?.settings !== undefined
+          ? { settings: options.settings.readMergedSettings() }
+          : {}),
+        ...(options?.providerDefinitions !== undefined
+          ? { providerDefinitions: options.providerDefinitions }
+          : {}),
+        refresh: true,
+      }),
+      success: false,
+    };
+  }
+
+  return {
+    message: `Model change requested: ${modelId}`,
+    success: true,
+    data: { modelId },
+    effects: [{ type: 'model-change-requested', modelId }],
+  };
+}

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

@@ -0,0 +1,164 @@
+import { describe, expect, it, vi } from 'vitest';
+import type {
+  ICommandHostContext,
+  IEditCheckpointRestoreResult,
+} from '@robota-sdk/agent-framework';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createPermissionsCommandModule } from '../permissions-command-module.js';
+
+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(options?: {
+  mode?: TPermissionModeName;
+  sessionAllowed?: readonly string[];
+}): ICommandHostContext & { setPermissionMode: TSetPermissionModeSpy } {
+  let mode = options?.mode ?? 'default';
+  const setPermissionMode = vi.fn((nextMode: TPermissionModeName) => {
+    mode = nextMode;
+  });
+
+  return {
+    getSession: () => {
+      throw new Error('permissions command should use the permission mode adapter');
+    },
+    getCommandHostAdapters: () => ({
+      permissionMode: {
+        getPermissionMode: () => mode,
+        setPermissionMode,
+        listSessionAllowedTools: () => options?.sessionAllowed ?? [],
+      },
+    }),
+    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('createPermissionsCommandModule', () => {
+  it('provides permissions metadata and user-only executable command from one module owner', () => {
+    const module = createPermissionsCommandModule();
+    const command = module.systemCommands?.[0];
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+
+    expect(module.name).toBe('agent-command-permissions');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'permissions',
+        description: 'Show/change permission mode and permission rules',
+        argumentHint: 'plan | default | acceptEdits | bypassPermissions',
+        source: 'permissions',
+        modelInvocable: false,
+      }),
+    );
+    expect(entry?.subcommands?.map((subcommand) => subcommand.name)).toEqual([
+      'plan',
+      'default',
+      'acceptEdits',
+      'bypassPermissions',
+    ]);
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'permissions',
+        description: 'Show/change permission mode and permission rules',
+        argumentHint: 'plan | default | acceptEdits | bypassPermissions',
+        lifecycle: 'inline',
+        modelInvocable: false,
+      }),
+    );
+    expect(command?.subcommands).toEqual(entry?.subcommands);
+  });
+
+  it('reports no session-approved tools when the command allowlist is empty', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createPermissionsCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('permissions', createCommandHostContext(), '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Permission mode: default\nNo session-approved tools.');
+    expect(result?.data).toEqual({ mode: 'default', sessionAllowed: [] });
+  });
+
+  it('reports session-approved tools when present', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createPermissionsCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute(
+      'permissions',
+      createCommandHostContext({ mode: 'acceptEdits', sessionAllowed: ['Bash', 'Read'] }),
+      '',
+    );
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe(
+      'Permission mode: acceptEdits\nSession-approved tools: Bash, Read',
+    );
+    expect(result?.data).toEqual({ mode: 'acceptEdits', sessionAllowed: ['Bash', 'Read'] });
+  });
+
+  it('updates valid permission modes through the SDK command adapter', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createPermissionsCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+
+    const result = await executor.execute('permissions', context, 'plan');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe(
+      'Permission mode set to: plan\nPermission mode: plan\nNo session-approved tools.',
+    );
+    expect(result?.data).toEqual({ mode: 'plan', sessionAllowed: [] });
+    expect(context.setPermissionMode).toHaveBeenCalledWith('plan');
+  });
+
+  it('rejects invalid permission modes without writing state', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createPermissionsCommandModule().systemCommands ?? []),
+    ]);
+    const context = createCommandHostContext();
+
+    const result = await executor.execute('permissions', context, 'invalid');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toBe(
+      'Invalid mode. Valid: plan | default | acceptEdits | bypassPermissions',
+    );
+    expect(context.setPermissionMode).not.toHaveBeenCalled();
+  });
+});

package/src/permissions/index.ts

@@ -0,0 +1,6 @@
+export {
+  createPermissionsCommandEntry,
+  createPermissionsCommandModule,
+  PermissionsCommandSource,
+} from './permissions-command-module.js';
+export { executePermissionsCommand } from './permissions-command.js';

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

@@ -0,0 +1,56 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import {
+  buildPermissionModeSubcommands,
+  PERMISSION_MODE_ARGUMENT_HINT,
+  PERMISSIONS_COMMAND_DESCRIPTION,
+} from '@robota-sdk/agent-framework';
+import { executePermissionsCommand } from './permissions-command.js';
+
+export function createPermissionsCommandEntry(): ICommand {
+  return {
+    name: 'permissions',
+    displayName: 'Permissions',
+    description: PERMISSIONS_COMMAND_DESCRIPTION,
+    source: 'permissions',
+    argumentHint: PERMISSION_MODE_ARGUMENT_HINT,
+    subcommands: buildPermissionModeSubcommands('permissions'),
+    modelInvocable: false,
+  };
+}
+
+function createPermissionsSystemCommand(): ISystemCommand {
+  const entry = createPermissionsCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: true,
+    userInvocable: true,
+    modelInvocable: false,
+    argumentHint: entry.argumentHint,
+    subcommands: entry.subcommands,
+    lifecycle: 'inline',
+    execute: executePermissionsCommand,
+  };
+}
+
+export class PermissionsCommandSource implements ICommandSource {
+  readonly name = 'permissions';
+
+  getCommands(): ICommand[] {
+    return [createPermissionsCommandEntry()];
+  }
+}
+
+export function createPermissionsCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-permissions',
+    commandSources: [new PermissionsCommandSource()],
+    systemCommands: [createPermissionsSystemCommand()],
+  };
+}

package/src/permissions/permissions-command.ts

@@ -0,0 +1,45 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import {
+  formatCommandPermissionsMessage,
+  formatInvalidPermissionModeMessage,
+  isPermissionMode,
+  parsePermissionModeArgument,
+  readCommandPermissionsState,
+  writeCommandPermissionMode,
+} from '@robota-sdk/agent-framework';
+
+export function executePermissionsCommand(
+  context: ICommandHostContext,
+  args: string,
+): ICommandResult {
+  const arg = parsePermissionModeArgument(args);
+  if (arg !== undefined) {
+    if (!isPermissionMode(arg)) {
+      return {
+        message: formatInvalidPermissionModeMessage(),
+        success: false,
+      };
+    }
+
+    writeCommandPermissionMode(context, arg);
+    const state = readCommandPermissionsState(context);
+    return {
+      message: `Permission mode set to: ${arg}\n${formatCommandPermissionsMessage(state)}`,
+      success: true,
+      data: {
+        mode: state.mode,
+        sessionAllowed: state.sessionAllowed,
+      },
+    };
+  }
+
+  const state = readCommandPermissionsState(context);
+  return {
+    message: formatCommandPermissionsMessage(state),
+    success: true,
+    data: {
+      mode: state.mode,
+      sessionAllowed: state.sessionAllowed,
+    },
+  };
+}