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

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

@@ -0,0 +1,339 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/agent-framework';
+import { InteractiveSession, SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createSessionCommandModule } from '../session-command-module.js';
+
+function createRuntime(): ICommandSessionRuntime {
+  return {
+    clearHistory: vi.fn(),
+    compact: async () => undefined,
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 0,
+      usedPercentage: 0,
+      remainingPercentage: 100,
+    }),
+    getPermissionMode: () => 'default',
+    setPermissionMode: () => undefined,
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 5,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => false,
+  };
+}
+
+function createCommandContext(): ICommandHostContext {
+  const runtime = createRuntime();
+  return {
+    getSession: () => runtime,
+    getContextState: () => runtime.getContextState(),
+    getAutoCompactThreshold: () => 0.835,
+    compactContext: async () => undefined,
+    getCwd: () => '/workspace',
+    listEditCheckpoints: () => [],
+    restoreEditCheckpoint: async () => {
+      throw new Error('not used');
+    },
+    rollbackEditCheckpoint: async () => {
+      throw new Error('not used');
+    },
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: () => undefined,
+    listBackgroundTasks: () => [],
+    readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+    cancelBackgroundTask: async () => undefined,
+    closeBackgroundTask: async () => undefined,
+  };
+}
+
+describe('createSessionCommandModule', () => {
+  it('provides clear metadata and user-only executable command from one module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'clear');
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'clear');
+
+    expect(module.name).toBe('agent-command-session');
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'clear',
+        description: 'Clear conversation history',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'clear',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('provides rename metadata and user-only executable command from the same module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'rename');
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'rename');
+
+    expect(module.commandSources?.[0]?.getCommands().map((item) => item.name)).toEqual([
+      'clear',
+      'rename',
+      'resume',
+      'cost',
+      'validate-session',
+    ]);
+    expect(module.systemCommands?.map((item) => item.name)).toEqual([
+      'clear',
+      'rename',
+      'resume',
+      'cost',
+      'validate-session',
+    ]);
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'rename',
+        description: 'Rename the current session',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'rename',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('provides resume metadata and user-only executable command from the same module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'resume');
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'resume');
+
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'resume',
+        description: 'Resume a previous session',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'resume',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('provides cost metadata and user-only executable command from the same module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'cost');
+    const entry = module.commandSources?.[0]?.getCommands().find((item) => item.name === 'cost');
+
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'cost',
+        description: 'Show session info',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'cost',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('provides validate-session metadata and user-only executable command from the same module owner', () => {
+    const module = createSessionCommandModule();
+    const command = module.systemCommands?.find((item) => item.name === 'validate-session');
+    const entry = module.commandSources?.[0]
+      ?.getCommands()
+      .find((item) => item.name === 'validate-session');
+
+    expect(entry).toEqual(
+      expect.objectContaining({
+        name: 'validate-session',
+        description: 'Validate current session replay log',
+        source: 'session',
+        modelInvocable: false,
+      }),
+    );
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'validate-session',
+        lifecycle: 'inline',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+  });
+
+  it('clears conversation history through the session command API', async () => {
+    const clearConversationHistory = vi.fn();
+    const context = {
+      ...createCommandContext(),
+      clearConversationHistory,
+    };
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('clear', context, '');
+
+    expect(clearConversationHistory).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({
+      success: true,
+      message: 'Conversation cleared.',
+      effects: [{ type: 'conversation-history-cleared' }],
+    });
+  });
+
+  it('falls back to runtime clearHistory when the host has not implemented the richer API', async () => {
+    const runtime = createRuntime();
+    const context = {
+      ...createCommandContext(),
+      getSession: () => runtime,
+    };
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('clear', context, '');
+
+    expect(runtime.clearHistory).toHaveBeenCalledTimes(1);
+    expect(result?.success).toBe(true);
+  });
+
+  it('clears InteractiveSession history when executed through a composed session', async () => {
+    const clearHistory = vi.fn();
+    const runtime = {
+      ...createRuntime(),
+      clearHistory,
+      run: vi.fn().mockResolvedValue('answer'),
+      abort: vi.fn(),
+      getHistory: vi.fn().mockReturnValue([]),
+      injectMessage: vi.fn(),
+      getSystemMessage: vi.fn().mockReturnValue('system'),
+      getToolSchemas: vi.fn().mockReturnValue([]),
+    };
+    const session = new InteractiveSession({
+      session: runtime as never,
+      commandModules: [createSessionCommandModule()],
+    });
+    await session.submit('hello');
+    expect(session.getFullHistory().length).toBeGreaterThan(0);
+
+    const result = await session.executeCommand('clear', '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Conversation cleared.',
+      effects: [{ type: 'conversation-history-cleared' }],
+    });
+    expect(clearHistory).toHaveBeenCalledTimes(1);
+    expect(session.getFullHistory()).toEqual([]);
+  });
+
+  it('renames the current session through a typed host effect', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('rename', createCommandContext(), ' my-session ');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Session renamed to "my-session".',
+      data: { name: 'my-session' },
+      effects: [{ type: 'session-renamed', name: 'my-session' }],
+    });
+  });
+
+  it('returns usage when rename is missing a session name', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('rename', createCommandContext(), '  ');
+
+    expect(result).toEqual({
+      success: false,
+      message: 'Usage: rename <name>',
+    });
+  });
+
+  it('requests the host session picker through a typed effect', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('resume', createCommandContext(), '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Opening session picker...',
+      data: { triggerResumePicker: true },
+      effects: [{ type: 'session-picker-requested' }],
+    });
+  });
+
+  it('shows session info through the session command API', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+
+    const result = await executor.execute('cost', createCommandContext(), '');
+
+    expect(result).toEqual({
+      success: true,
+      message: 'Session: session_1\nMessages: 5',
+      data: { sessionId: 'session_1', messageCount: 5 },
+    });
+  });
+
+  it('validates the current session replay log through the SDK common API', async () => {
+    const executor = new SystemCommandExecutor([
+      ...(createSessionCommandModule().systemCommands ?? []),
+    ]);
+    const context = {
+      ...createCommandContext(),
+      validateCurrentSessionReplayLog: () => ({
+        logFile: '/workspace/.robota/logs/session_1.jsonl',
+        entryCount: 2,
+        validation: {
+          ok: false,
+          issues: [
+            {
+              code: 'PROVIDER_NATIVE_RAW_PAYLOAD_MISSING' as const,
+              message: 'Provider request exec-1:1 has no provider-native payload.',
+              executionId: 'exec-1',
+              round: 1,
+            },
+          ],
+        },
+      }),
+    };
+
+    const result = await executor.execute('validate-session', context, '');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('PROVIDER_NATIVE_RAW_PAYLOAD_MISSING');
+    expect(result?.data).toEqual({
+      logFile: '/workspace/.robota/logs/session_1.jsonl',
+      entryCount: 2,
+      issueCount: 1,
+      ok: false,
+    });
+  });
+});

package/src/session/index.ts

@@ -0,0 +1,17 @@
+export {
+  executeClearCommand,
+  executeCostCommand,
+  executeRenameCommand,
+  executeResumeCommand,
+  executeValidateSessionCommand,
+  CLEAR_COMMAND_MESSAGE,
+} from './session-command.js';
+export {
+  SessionCommandSource,
+  createClearCommandEntry,
+  createCostCommandEntry,
+  createRenameCommandEntry,
+  createResumeCommandEntry,
+  createSessionCommandModule,
+  createValidateSessionCommandEntry,
+} from './session-command-module.js';

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

@@ -0,0 +1,168 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import {
+  CLEAR_COMMAND_DESCRIPTION,
+  COST_COMMAND_DESCRIPTION,
+  RENAME_COMMAND_DESCRIPTION,
+  RESUME_COMMAND_DESCRIPTION,
+  VALIDATE_SESSION_COMMAND_DESCRIPTION,
+} from '@robota-sdk/agent-framework';
+import {
+  executeClearCommand,
+  executeCostCommand,
+  executeRenameCommand,
+  executeResumeCommand,
+  executeValidateSessionCommand,
+} from './session-command.js';
+
+export function createClearCommandEntry(): ICommand {
+  return {
+    name: 'clear',
+    displayName: 'Clear History',
+    description: CLEAR_COMMAND_DESCRIPTION,
+    source: 'session',
+    modelInvocable: false,
+  };
+}
+
+export function createRenameCommandEntry(): ICommand {
+  return {
+    name: 'rename',
+    displayName: 'Rename Session',
+    description: RENAME_COMMAND_DESCRIPTION,
+    source: 'session',
+    modelInvocable: false,
+  };
+}
+
+export function createResumeCommandEntry(): ICommand {
+  return {
+    name: 'resume',
+    displayName: 'Resume Session',
+    description: RESUME_COMMAND_DESCRIPTION,
+    source: 'session',
+    modelInvocable: false,
+  };
+}
+
+export function createCostCommandEntry(): ICommand {
+  return {
+    name: 'cost',
+    displayName: 'Session Cost',
+    description: COST_COMMAND_DESCRIPTION,
+    source: 'session',
+    modelInvocable: false,
+  };
+}
+
+export function createValidateSessionCommandEntry(): ICommand {
+  return {
+    name: 'validate-session',
+    displayName: 'Validate Session',
+    description: VALIDATE_SESSION_COMMAND_DESCRIPTION,
+    source: 'session',
+    modelInvocable: false,
+  };
+}
+
+function createClearSystemCommand(): ISystemCommand {
+  const entry = createClearCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeClearCommand,
+  };
+}
+
+function createRenameSystemCommand(): ISystemCommand {
+  const entry = createRenameCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeRenameCommand,
+  };
+}
+
+function createResumeSystemCommand(): ISystemCommand {
+  const entry = createResumeCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeResumeCommand,
+  };
+}
+
+function createCostSystemCommand(): ISystemCommand {
+  const entry = createCostCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeCostCommand,
+  };
+}
+
+function createValidateSessionSystemCommand(): ISystemCommand {
+  const entry = createValidateSessionCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeValidateSessionCommand,
+  };
+}
+
+export class SessionCommandSource implements ICommandSource {
+  readonly name = 'session';
+
+  getCommands(): ICommand[] {
+    return [
+      createClearCommandEntry(),
+      createRenameCommandEntry(),
+      createResumeCommandEntry(),
+      createCostCommandEntry(),
+      createValidateSessionCommandEntry(),
+    ];
+  }
+}
+
+export function createSessionCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-session',
+    commandSources: [new SessionCommandSource()],
+    systemCommands: [
+      createClearSystemCommand(),
+      createRenameSystemCommand(),
+      createResumeSystemCommand(),
+      createCostSystemCommand(),
+      createValidateSessionSystemCommand(),
+    ],
+  };
+}

package/src/session/session-command.ts

@@ -0,0 +1,74 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import {
+  RENAME_COMMAND_USAGE,
+  clearConversationHistory,
+  createSessionPickerRequestedEffect,
+  createSessionRenamedEffect,
+  formatCommandSessionReplayValidationReport,
+  parseSessionNameArgument,
+  readCommandSessionInfo,
+  validateCommandSessionReplayLog,
+} from '@robota-sdk/agent-framework';
+
+export const CLEAR_COMMAND_MESSAGE = 'Conversation cleared.';
+
+export function executeClearCommand(context: ICommandHostContext, _args: string): ICommandResult {
+  clearConversationHistory(context);
+  return {
+    success: true,
+    message: CLEAR_COMMAND_MESSAGE,
+    effects: [{ type: 'conversation-history-cleared' }],
+  };
+}
+
+export function executeRenameCommand(_context: ICommandHostContext, args: string): ICommandResult {
+  const name = parseSessionNameArgument(args);
+  if (name === undefined) {
+    return { success: false, message: RENAME_COMMAND_USAGE };
+  }
+
+  return {
+    success: true,
+    message: `Session renamed to "${name}".`,
+    data: { name },
+    effects: [createSessionRenamedEffect(name)],
+  };
+}
+
+export function executeResumeCommand(_context: ICommandHostContext, _args: string): ICommandResult {
+  return {
+    success: true,
+    message: 'Opening session picker...',
+    data: { triggerResumePicker: true },
+    effects: [createSessionPickerRequestedEffect()],
+  };
+}
+
+export function executeCostCommand(context: ICommandHostContext, _args: string): ICommandResult {
+  const sessionInfo = readCommandSessionInfo(context);
+  return {
+    success: true,
+    message: `Session: ${sessionInfo.sessionId}\nMessages: ${sessionInfo.messageCount}`,
+    data: {
+      sessionId: sessionInfo.sessionId,
+      messageCount: sessionInfo.messageCount,
+    },
+  };
+}
+
+export function executeValidateSessionCommand(
+  context: ICommandHostContext,
+  _args: string,
+): ICommandResult {
+  const report = validateCommandSessionReplayLog(context);
+  return {
+    success: report.validation.ok,
+    message: formatCommandSessionReplayValidationReport(report),
+    data: {
+      logFile: report.logFile,
+      entryCount: report.entryCount,
+      issueCount: report.validation.issues.length,
+      ok: report.validation.ok,
+    },
+  };
+}

package/src/settings/index.ts

@@ -0,0 +1,7 @@
+// @robota-sdk/agent-command-settings
+
+export {
+  createSettingsCommandModule,
+  createSettingsCommandEntry,
+  SettingsCommandSource,
+} from './settings-command-module.js';

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

@@ -0,0 +1,50 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+
+export function createSettingsCommandEntry(): ICommand {
+  return {
+    name: 'settings',
+    displayName: 'Settings',
+    description: 'Open transport settings — enable/disable transports and configure options',
+    source: 'settings',
+    modelInvocable: false,
+  };
+}
+
+function createSettingsSystemCommand(): ISystemCommand {
+  const entry = createSettingsCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: async () => ({
+      success: true,
+      message: 'Opening settings...',
+      effects: [{ type: 'settings-tui-requested' as const }],
+    }),
+  };
+}
+
+export class SettingsCommandSource implements ICommandSource {
+  readonly name = 'settings';
+
+  getCommands(): ICommand[] {
+    return [createSettingsCommandEntry()];
+  }
+}
+
+export function createSettingsCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-settings',
+    commandSources: [new SettingsCommandSource()],
+    systemCommands: [createSettingsSystemCommand()],
+  };
+}