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

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

@@ -0,0 +1,130 @@
+import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/agent-framework';
+import type { ICommandListEntry } from '@robota-sdk/agent-interface-command';
+import { formatCommandHelpMessage } from '@robota-sdk/agent-framework';
+import { describe, expect, it } from 'vitest';
+import {
+  createTestCommandHost,
+  createTestSessionRuntime,
+} from '@robota-sdk/agent-framework/testing';
+
+function createCommandSessionRuntime() {
+  return createTestSessionRuntime({
+    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,
+    getFullHistory: () => [],
+    getHistory: () => [],
+  });
+}
+
+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[]) {
+  const checkpoint = createCheckpoint();
+  return createTestCommandHost({
+    overrides: {
+      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',
+        modelInvocable: true,
+        runner: 'runtime',
+      },
+    ]);
+
+    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',
+        modelInvocable: true,
+        runner: 'runtime',
+      },
+    ]);
+
+    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',
+        modelInvocable: true,
+        runner: 'runtime',
+      },
+    ]);
+
+    const output = formatCommandHelpMessage(context);
+
+    expect(output).not.toContain('Example:');
+  });
+});

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

@@ -0,0 +1,47 @@
+import { HELP_COMMAND_DESCRIPTION } from '@robota-sdk/agent-framework';
+
+import { executeHelpCommand } from './help-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createHelpCommandEntry(): ICommand {
+  return {
+    name: 'help',
+    displayName: 'Help',
+    description: HELP_COMMAND_DESCRIPTION,
+    source: 'help',
+    // User-only: a listing for the user; the model already sees the commands it may run.
+    modelInvocable: false,
+  };
+}
+
+function createHelpSystemCommand(): ISystemCommand {
+  const entry = createHelpCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeHelpCommand,
+  };
+}
+
+export class HelpCommandSource implements ICommandSource {
+  readonly name = 'help';
+
+  getCommands(): ICommand[] {
+    return [createHelpCommandEntry()];
+  }
+}
+
+export function createHelpCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-help',
+    commandSources: [new HelpCommandSource()],
+    systemCommands: [createHelpSystemCommand()],
+  };
+}

package/src/help/help-command.ts

@@ -0,0 +1,11 @@
+import { formatCommandHelpMessage } from '@robota-sdk/agent-framework';
+
+import type { ICommandHostCatalog } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+export function executeHelpCommand(context: ICommandHostCatalog, _args: string): ICommandResult {
+  return {
+    success: true,
+    message: formatCommandHelpMessage(context),
+  };
+}

package/src/help/index.ts

@@ -0,0 +1,6 @@
+export {
+  createHelpCommandEntry,
+  createHelpCommandModule,
+  HelpCommandSource,
+} from './help-command-module.js';
+export { executeHelpCommand } from './help-command.js';

package/src/index.ts

@@ -0,0 +1,163 @@
+export * from './agent/index.js';
+export * from './default/index.js';
+export * from './background/index.js';
+export * from './goal/index.js';
+// HANDOFF-001 (issue #1864). Named rather than `export *`: the star form is frozen pre-existing
+// debt in this barrel, and `sdk-public-surface` lets it shrink but never grow.
+export {
+  HandoffCommandSource,
+  createHandoffCommandEntry,
+  createHandoffCommandModule,
+  executeHandoffCommand,
+} from './handoff/index.js';
+export * from './plan/index.js';
+export * from './compact/index.js';
+export * from './context/index.js';
+export * from './editor/index.js';
+export {
+  createGitCommandEntry,
+  createGitCommandModule,
+  createGitProcess,
+  executeGitCommand,
+  gitEnvironment,
+  GitCommandSource,
+  type ICreateGitProcessOptions,
+  type IGitCommandModuleOptions,
+  type IGitProcessPort,
+  type IGitProcessRunOptions,
+  type TGitCommandContext,
+  type TGitProcessFailureReason,
+  type TGitProcessOutcome,
+} from './git/index.js';
+// OBSERVABILITY-1991: named rather than `export *` — the star form is frozen debt in this barrel.
+export {
+  STORAGE_REPAIR_ID,
+  doctorRepairAllowlist,
+  DoctorCommandSource,
+  applyDoctorRepair,
+  buildDoctorReport,
+  collectSettingsSecrets,
+  createDoctorCommandEntry,
+  createDoctorCommandModule,
+  createNodeDoctorDeps,
+  isDoctorRepairId,
+  planDoctorRepair,
+  redactDiagnosticText,
+  renderDoctorReport,
+  type IDoctorDisplayVocabulary,
+  resolveCommandOnPath,
+  runDoctor,
+  type IDoctorCheck,
+  type IDoctorDeps,
+  type IDoctorEndpointProbeResult,
+  type IDoctorInputs,
+  type IDoctorPathFacts,
+  type IDoctorRepairPlan,
+  type IDoctorReport,
+  type TDoctorCheckStatus,
+  type TDoctorNotProbed,
+  type TDoctorRepairOutcome,
+  type TDoctorRepairPlanResult,
+} from './doctor/index.js';
+export {
+  EffortCommandSource,
+  createEffortCommandEntry,
+  createEffortCommandModule,
+  executeEffortCommand,
+} from './effort/index.js';
+export {
+  ADVISOR_SETTING_KEY,
+  AdvisorCommandSource,
+  createAdvisorCommandEntry,
+  createAdvisorCommandModule,
+  executeAdvisorCommand,
+} from './advisor/index.js';
+export * from './exit/index.js';
+export * from './help/index.js';
+export {
+  createDevicesCommandModule,
+  type IDeviceListEntry,
+  type IDevicesCommandPort,
+  type IDevicesInitResult,
+  type IDevicesAddResult,
+  type IDevicesJoinResult,
+  type IDevicesRecoverResult,
+  type IDevicesRevokeResult,
+  type IDevicesMeshStatus,
+  type IDevicesView,
+  type TDevicesOutcome,
+  type TDevicesRefusal,
+} from './devices/index.js';
+export {
+  createKeybindingsCommandEntry,
+  createKeybindingsCommandModule,
+  KeybindingsCommandSource,
+  type IKeybindingsFilePort,
+} from './keybindings/index.js';
+export {
+  createThemeCommandEntry,
+  createThemeCommandModule,
+  executeThemeCommand,
+  ThemeCommandSource,
+} from './theme/index.js';
+// Re-exported from the contract package so a composition root that depends on this package — the
+// CLI — can name the port it injects without also depending on the interface package directly.
+export type {
+  IThemeAppearanceState,
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+  TReducedMotionOverride,
+} from './theme/index.js';
+export * from './language/index.js';
+export * from './memory/index.js';
+export {
+  createMCPActivationCommandEntry,
+  createMCPActivationCommandModule,
+  MCPActivationCommandSource,
+} from './mcp-activation/mcp-activation-command-module.js';
+export { executeMCPActivationCommand } from './mcp-activation/mcp-activation-command.js';
+export {
+  mcpUnavailableServersNotice,
+  mcpUserActionCommand,
+  mcpUserActionNotice,
+} from './mcp-activation/mcp-model-notice.js';
+export type { TMCPUserAction, TMCPUserActionSurface } from './mcp-activation/mcp-model-notice.js';
+export * from './mode/index.js';
+export {
+  createModelCommandEntry,
+  createModelCommandModule,
+  ModelCommandSource,
+} from './model/model-command-module.js';
+export { executeModelCommand } from './model/model-command.js';
+export {
+  createSandboxCommandModule,
+  executeSandboxCommand,
+  formatSandboxStatus,
+  SANDBOX_MODES,
+  SandboxCommandSource,
+} from './sandbox/index.js';
+export {
+  OutputStyleCommandSource,
+  createOutputStyleCommandEntry,
+  createOutputStyleCommandModule,
+  executeOutputStyleCommand,
+} from './output-style/index.js';
+export * from './permissions/index.js';
+export * from './plugin/index.js';
+export * from './preset/index.js';
+export * from './shell/index.js';
+export * from './provider/index.js';
+export * from './remote-control/index.js';
+export * from './reset/index.js';
+export * from './rewind/index.js';
+export * from './schedule/index.js';
+export * from './session/index.js';
+export * from './settings/index.js';
+export * from './skills/index.js';
+export * from './statusline/index.js';
+export {
+  createTerminalClientCommands,
+  type ITerminalClientCommand,
+  type ITerminalClientCommandOptions,
+} from './terminal-client/index.js';
+export * from './user-local/index.js';

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

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { scriptedSession } from '@robota-sdk/agent-framework/testing';
+
+import { createKeybindingsCommandModule } from '../keybindings-command-module.js';
+
+import type { ITerminalHandoff } from '@robota-sdk/agent-interface-session';
+
+function handoff(enabled: boolean): ITerminalHandoff {
+  return {
+    canHandoffTerminal: enabled,
+    runWithTerminal: async (operation) => operation(),
+  };
+}
+
+describe('/keybindings command', () => {
+  it('ensures and opens the exact capability-owned path', async () => {
+    const ensureFile = vi.fn().mockResolvedValue('/tmp/keybindings.json');
+    const previous = process.env.EDITOR;
+    process.env.EDITOR = 'true';
+    const session = scriptedSession({
+      turns: [{ text: 'unused' }],
+      terminalHandoff: handoff(true),
+      commandModules: [createKeybindingsCommandModule({ ensureFile })],
+    });
+    try {
+      const result = await session.command('keybindings', '');
+      expect(result).toMatchObject({
+        success: true,
+        message: 'Opened keybindings: /tmp/keybindings.json',
+        data: { path: '/tmp/keybindings.json' },
+      });
+      expect(ensureFile).toHaveBeenCalledTimes(1);
+    } finally {
+      await session.dispose();
+      if (previous === undefined) delete process.env.EDITOR;
+      else process.env.EDITOR = previous;
+    }
+  });
+
+  it('reports an unavailable terminal without creating a file', async () => {
+    const ensureFile = vi.fn().mockResolvedValue('/tmp/keybindings.json');
+    const session = scriptedSession({
+      turns: [{ text: 'unused' }],
+      terminalHandoff: handoff(false),
+      commandModules: [createKeybindingsCommandModule({ ensureFile })],
+    });
+    try {
+      const result = await session.command('keybindings', '');
+      expect(result?.success).toBe(false);
+      expect(result?.message).toMatch(/unavailable/i);
+      expect(ensureFile).not.toHaveBeenCalled();
+    } finally {
+      await session.dispose();
+    }
+  });
+});

package/src/keybindings/index.ts

@@ -0,0 +1,6 @@
+export {
+  createKeybindingsCommandEntry,
+  createKeybindingsCommandModule,
+  KeybindingsCommandSource,
+  type IKeybindingsFilePort,
+} from './keybindings-command-module.js';

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

@@ -0,0 +1,88 @@
+import { resolveEditor } from '../editor/resolve-editor.js';
+import { spawnInherited } from '../shell/spawn-inherited.js';
+
+import type {
+  ICommandHostTerminalHandoff,
+  ICommandHostWorkspace,
+  ICommandModule,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandResult, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export interface IKeybindingsFilePort {
+  ensureFile(): Promise<string>;
+}
+
+export function createKeybindingsCommandEntry(): ICommand {
+  return {
+    name: 'keybindings',
+    displayName: 'Keybindings',
+    description: 'Open the contextual terminal keybindings file in $EDITOR',
+    source: 'keybindings',
+    // User-only: UI preference.
+    modelInvocable: false,
+    // Key bindings belong to the terminal the user sits at, so that terminal runs it, even when
+    // attached.
+    runner: 'client',
+    surfaces: ['terminal'],
+  };
+}
+
+// A host without a terminal (the desktop app's sidecar) still answers, so the command is never
+// "unknown" there — it says where key bindings live instead.
+const KEYBINDINGS_UNAVAILABLE =
+  'Key bindings are available in an interactive terminal. Run /keybindings there.';
+
+export async function executeKeybindingsCommand(
+  file: IKeybindingsFilePort | undefined,
+  context: ICommandHostTerminalHandoff & ICommandHostWorkspace,
+): Promise<ICommandResult> {
+  if (!file) return { success: false, message: KEYBINDINGS_UNAVAILABLE };
+  if (!context.canHandoffTerminal()) {
+    return { success: false, message: 'Keybindings editor is unavailable here.' };
+  }
+  const path = await file.ensureFile();
+  const editor = resolveEditor();
+  const exitCode = await context.runWithTerminal(() =>
+    spawnInherited(editor.command, [...editor.args, path], context.getCwd()),
+  );
+  if (exitCode !== 0) {
+    return {
+      success: false,
+      message: `Keybindings editor exited with code ${exitCode}.`,
+      data: { path, exitCode },
+    };
+  }
+  return { success: true, message: `Opened keybindings: ${path}`, data: { path } };
+}
+
+export class KeybindingsCommandSource implements ICommandSource {
+  readonly name = 'keybindings';
+
+  getCommands(): ICommand[] {
+    return [createKeybindingsCommandEntry()];
+  }
+}
+
+export function createKeybindingsCommandModule(
+  file: IKeybindingsFilePort | undefined,
+): ICommandModule {
+  const entry = createKeybindingsCommandEntry();
+  const command: ISystemCommand = {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    runner: entry.runner,
+    surfaces: entry.surfaces,
+    lifecycle: 'inline',
+    execute: (context) => executeKeybindingsCommand(file, context),
+  };
+  return {
+    name: 'agent-command-keybindings',
+    commandSources: [new KeybindingsCommandSource()],
+    systemCommands: [command],
+  };
+}

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  ICommandHostContext,
+  IEditCheckpointRestoreResult,
+} from '@robota-sdk/agent-framework';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createLanguageCommandModule } from '../language-command-module.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+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 = createTestCommandHost({
+  overrides: {
+    getSession: () => {
+      throw new Error('language 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,
+  },
+});
+
+describe('createLanguageCommandModule', () => {
+  it('provides language metadata and executable command from one module owner', () => {
+    const module = createLanguageCommandModule();
+    const command = module.systemCommands?.[0];
+    const entry = module.commandSources?.[0]?.getCommands()[0];
+
+    expect(module.name).toBe('agent-command-language');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'language',
+        description: 'Set response language',
+        argumentHint: '<code>',
+        source: 'language',
+        modelInvocable: false,
+      }),
+    );
+    expect(entry?.subcommands?.map((subcommand) => subcommand.name)).toEqual([
+      'ko',
+      'en',
+      'ja',
+      'zh',
+    ]);
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'language',
+        description: 'Set response language',
+        argumentHint: '<code>',
+        lifecycle: 'inline',
+        modelInvocable: false,
+      }),
+    );
+    expect(command?.subcommands).toEqual(entry?.subcommands);
+  });
+
+  it('requests language changes through a typed command effect', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createLanguageCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('language', commandHostContext, 'ko');
+
+    expect(result?.success).toBe(true);
+    expect(result?.data?.language).toBe('ko');
+    expect(result?.hostActions).toEqual([{ type: 'language-change', language: 'ko' }]);
+  });
+
+  it('shows usage when no language code is provided', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createLanguageCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('language', commandHostContext, '');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toBe('Usage: language <code> (e.g., ko, en, ja, zh)');
+  });
+
+  it('asks the user to pick a language when none is provided (CMD-004)', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createLanguageCommandModule().systemCommands ?? []),
+    ]);
+    const contextWithAsk = createTestCommandHost({
+      overrides: {
+        ...commandHostContext,
+        getUserInteraction: () => ({ ask: async () => ({ type: 'answer', values: ['ko'] }) }),
+      },
+    });
+
+    const result = await executor.execute('language', contextWithAsk, '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.data?.language).toBe('ko');
+    expect(result?.hostActions).toEqual([{ type: 'language-change', language: 'ko' }]);
+  });
+});

package/src/language/index.ts

@@ -0,0 +1,6 @@
+export {
+  createLanguageCommandEntry,
+  createLanguageCommandModule,
+  LanguageCommandSource,
+} from './language-command-module.js';
+export { executeLanguageCommand } from './language-command.js';