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

package/src/memory/memory-command.ts

@@ -0,0 +1,234 @@
+import type {
+  IAppendMemoryInput,
+  ICommandHostContext,
+  ICommandPendingMemoryStore,
+  ICommandProjectMemoryStore,
+  ICommandResult,
+  IMemoryEvent,
+} from '@robota-sdk/agent-framework';
+import {
+  MEMORY_COMMAND_USAGE,
+  createCommandMemoryStores,
+  hasSensitiveCommandMemoryContent,
+  isCommandMemoryType,
+  listCommandUsedMemoryReferences,
+  recordCommandMemoryEvent,
+} from '@robota-sdk/agent-framework';
+
+const SUBCOMMAND_INDEX = 0;
+const TYPE_INDEX = 1;
+const TOPIC_INDEX = 2;
+const TEXT_START_INDEX = 3;
+
+function usage(): ICommandResult {
+  return {
+    message: MEMORY_COMMAND_USAGE,
+    success: false,
+  };
+}
+
+function formatError(error: Error | string): ICommandResult {
+  return {
+    message: error instanceof Error ? error.message : String(error),
+    success: false,
+  };
+}
+
+function formatList(store: ICommandProjectMemoryStore): ICommandResult {
+  const summary = store.list();
+  const topics =
+    summary.topics.length > 0
+      ? summary.topics.map((topic) => `- ${topic.name}: ${topic.path}`).join('\n')
+      : '(none)';
+
+  return {
+    message: [
+      `Memory index: ${summary.indexPath}`,
+      `Topics directory: ${summary.topicsPath}`,
+      'Topics:',
+      topics,
+    ].join('\n'),
+    success: true,
+    data: {
+      indexPath: summary.indexPath,
+      topicsPath: summary.topicsPath,
+      topicCount: summary.topics.length,
+    },
+  };
+}
+
+function formatShow(store: ICommandProjectMemoryStore, topic?: string): ICommandResult {
+  if (!topic || topic === 'index') {
+    const memory = store.loadStartupMemory();
+    return {
+      message: memory.content || '(empty memory index)',
+      success: true,
+      data: {
+        path: memory.path,
+        lineCount: memory.lineCount,
+        truncated: memory.truncated,
+      },
+    };
+  }
+
+  const content = store.readTopic(topic);
+  return {
+    message: content || `(empty memory topic: ${topic})`,
+    success: true,
+    data: { topic },
+  };
+}
+
+function parseAdd(args: readonly string[]): IAppendMemoryInput | undefined {
+  const type = args[TYPE_INDEX];
+  const topic = args[TOPIC_INDEX];
+  const text = args.slice(TEXT_START_INDEX).join(' ').trim();
+
+  if (!type || !isCommandMemoryType(type) || !topic || text.length === 0) return undefined;
+  return { type, topic, text };
+}
+
+function formatPending(store: ICommandPendingMemoryStore): ICommandResult {
+  const records = store.list('pending');
+  const lines =
+    records.length > 0
+      ? records.map(
+          (record) =>
+            `- ${record.id} ${record.type}/${record.topic} confidence=${record.confidence}: ${record.text}`,
+        )
+      : ['(no pending memory candidates)'];
+
+  return {
+    message: ['Pending memory candidates:', ...lines].join('\n'),
+    success: true,
+    data: { count: records.length },
+  };
+}
+
+function recordEvent(context: ICommandHostContext, event: Omit<IMemoryEvent, 'at'>): void {
+  recordCommandMemoryEvent(context, event);
+}
+
+function approvePending(
+  context: ICommandHostContext,
+  pendingStore: ICommandPendingMemoryStore,
+  memoryStore: ICommandProjectMemoryStore,
+  id: string | undefined,
+): ICommandResult {
+  if (!id) return usage();
+  try {
+    const approved = pendingStore.mark(id, 'approved', 'approved-by-user');
+    const saved = memoryStore.append(approved);
+    const record = pendingStore.mark(id, 'saved', 'approved-and-saved');
+    recordEvent(context, {
+      type: 'memory_candidate_approved',
+      candidateId: record.id,
+      topic: record.topic,
+      reason: 'approved-by-user',
+    });
+    recordEvent(context, {
+      type: 'memory_candidate_saved',
+      candidateId: record.id,
+      topic: record.topic,
+      reason: saved.deduplicated ? 'deduplicated' : 'approved-and-saved',
+    });
+    return {
+      message: saved.deduplicated
+        ? `Saved memory candidate ${id} was already present in ${saved.topicPath}`
+        : `Saved memory candidate ${id} to ${saved.topicPath}`,
+      success: true,
+      data: {
+        id,
+        status: record.status,
+        topic: saved.topic,
+        topicPath: saved.topicPath,
+        deduplicated: saved.deduplicated,
+      },
+    };
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
+function rejectPending(
+  context: ICommandHostContext,
+  pendingStore: ICommandPendingMemoryStore,
+  id: string | undefined,
+): ICommandResult {
+  if (!id) return usage();
+  try {
+    const record = pendingStore.mark(id, 'rejected', 'rejected-by-user');
+    recordEvent(context, {
+      type: 'memory_candidate_rejected',
+      candidateId: record.id,
+      topic: record.topic,
+      reason: 'rejected-by-user',
+    });
+    return {
+      message: `Rejected memory candidate ${id}`,
+      success: true,
+      data: { id, status: record.status },
+    };
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
+function formatUsed(context: ICommandHostContext): ICommandResult {
+  const references = listCommandUsedMemoryReferences(context);
+  const lines =
+    references.length > 0
+      ? references.map((reference) => {
+          const suffix = reference.truncated ? ' truncated=true' : '';
+          return `- ${reference.topic} score=${reference.score}${suffix}: ${reference.path}`;
+        })
+      : ['(no memory used in current turn)'];
+
+  return {
+    message: ['Used memory references:', ...lines].join('\n'),
+    success: true,
+    data: { count: references.length, references: [...references] },
+  };
+}
+
+export function executeMemoryCommand(
+  context: ICommandHostContext,
+  rawArgs: string,
+): ICommandResult {
+  const args = rawArgs.trim().split(/\s+/).filter(Boolean);
+  const subcommand = args[SUBCOMMAND_INDEX] ?? 'list';
+  const stores = createCommandMemoryStores(context);
+
+  if (subcommand === 'list') return formatList(stores.project);
+  if (subcommand === 'show') return formatShow(stores.project, args[TYPE_INDEX]);
+  if (subcommand === 'pending') return formatPending(stores.pending);
+  if (subcommand === 'approve')
+    return approvePending(context, stores.pending, stores.project, args[TYPE_INDEX]);
+  if (subcommand === 'reject') return rejectPending(context, stores.pending, args[TYPE_INDEX]);
+  if (subcommand === 'used') return formatUsed(context);
+  if (subcommand === 'add') {
+    const input = parseAdd(args);
+    if (!input) return usage();
+    if (hasSensitiveCommandMemoryContent(input.text)) {
+      return {
+        message: 'Refusing to save sensitive memory content.',
+        success: false,
+      };
+    }
+    const result = stores.project.append(input);
+    return {
+      message: result.deduplicated
+        ? `${input.type} memory already exists in ${result.topicPath}`
+        : `Saved ${input.type} memory to ${result.topicPath}`,
+      success: true,
+      data: {
+        indexPath: result.indexPath,
+        topicPath: result.topicPath,
+        topic: result.topic,
+        deduplicated: result.deduplicated,
+      },
+    };
+  }
+
+  return usage();
+}

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

@@ -0,0 +1,143 @@
+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';
+
+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(): ICommandHostContext & {
+  setPermissionMode: TSetPermissionModeSpy;
+} {
+  let mode: TPermissionModeName = 'default';
+  const setPermissionMode = vi.fn((nextMode: TPermissionModeName) => {
+    mode = nextMode;
+  });
+
+  return {
+    getSession: () => {
+      throw new Error('mode command should use the permission mode adapter');
+    },
+    getCommandHostAdapters: () => ({
+      permissionMode: {
+        getPermissionMode: () => mode,
+        setPermissionMode,
+        listSessionAllowedTools: () => [],
+      },
+    }),
+    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',
+        source: 'mode',
+        modelInvocable: false,
+      }),
+    );
+    expect(entry?.subcommands?.map((subcommand) => subcommand.name)).toEqual([
+      'plan',
+      'default',
+      'acceptEdits',
+      'bypassPermissions',
+    ]);
+    expect(command).toEqual(
+      expect.objectContaining({
+        name: 'mode',
+        description: 'Show/change permission mode',
+        argumentHint: 'plan | default | acceptEdits | bypassPermissions',
+        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',
+    );
+    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,56 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import {
+  buildPermissionModeSubcommands,
+  PERMISSION_MODE_ARGUMENT_HINT,
+  PERMISSION_MODE_COMMAND_DESCRIPTION,
+} from '@robota-sdk/agent-framework';
+import { executeModeCommand } from './mode-command.js';
+
+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'),
+    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,34 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import {
+  formatInvalidPermissionModeMessage,
+  isPermissionMode,
+  parsePermissionModeArgument,
+  readCommandPermissionMode,
+  writeCommandPermissionMode,
+} from '@robota-sdk/agent-framework';
+
+export function executeModeCommand(context: ICommandHostContext, args: string): ICommandResult {
+  const arg = parsePermissionModeArgument(args);
+  if (arg === undefined) {
+    const mode = readCommandPermissionMode(context);
+    return {
+      message: `Current mode: ${mode}`,
+      success: true,
+      data: { mode },
+    };
+  }
+
+  if (!isPermissionMode(arg)) {
+    return {
+      message: formatInvalidPermissionModeMessage(),
+      success: false,
+    };
+  }
+
+  writeCommandPermissionMode(context, arg);
+  return {
+    message: `Permission mode set to: ${arg}`,
+    success: true,
+    data: { mode: arg },
+  };
+}