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

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

@@ -0,0 +1,215 @@
+import { describe, expect, it, vi } from 'vitest';
+import type {
+  IEditCheckpointInspection,
+  IEditCheckpointRestoreResult,
+  IEditCheckpointSummary,
+} from '@robota-sdk/agent-framework';
+import { InteractiveSession } from '@robota-sdk/agent-framework';
+import { RewindCommandSource, createRewindCommandModule, executeRewindCommand } from '../index.js';
+
+function createCheckpoint(overrides: Partial<IEditCheckpointSummary> = {}): IEditCheckpointSummary {
+  return {
+    id: 'turn-0001',
+    sessionId: 'test-session-id',
+    sequence: 1,
+    prompt: 'change files',
+    createdAt: '2026-05-02T00:00:00.000Z',
+    fileCount: 2,
+    ...overrides,
+  };
+}
+
+function createRestoreResult(
+  overrides: Partial<IEditCheckpointRestoreResult> = {},
+): IEditCheckpointRestoreResult {
+  return {
+    target: createCheckpoint({ fileCount: 1 }),
+    restoredCheckpointCount: 2,
+    restoredFileCount: 3,
+    removedCheckpointCount: 2,
+    ...overrides,
+  };
+}
+
+function createInspection(
+  overrides: Partial<IEditCheckpointInspection> = {},
+): IEditCheckpointInspection {
+  return {
+    target: createCheckpoint({ fileCount: 1 }),
+    capturedFiles: [
+      {
+        originalPath: '/workspace/example.ts',
+        relativePath: 'example.ts',
+        existed: true,
+        restoreAction: 'restore-preimage',
+        snapshotAvailable: true,
+        snapshotSizeBytes: 12,
+      },
+    ],
+    restoreToCheckpoint: { checkpointIds: ['turn-0002'], fileCount: 1 },
+    rollbackThroughCheckpoint: { checkpointIds: ['turn-0001', 'turn-0002'], fileCount: 2 },
+    ...overrides,
+  };
+}
+
+function createMockRuntimeSession() {
+  return {
+    run: vi.fn().mockResolvedValue('mock response'),
+    abort: vi.fn(),
+    getHistory: vi.fn().mockReturnValue([]),
+    getContextState: vi.fn().mockReturnValue({
+      usedTokens: 5000,
+      maxTokens: 200000,
+      usedPercentage: 2.5,
+    }),
+    compact: vi.fn().mockResolvedValue(undefined),
+    injectMessage: vi.fn(),
+    getSessionId: vi.fn().mockReturnValue('test-session-id'),
+    getSystemMessage: vi.fn().mockReturnValue('mock system prompt'),
+    getToolSchemas: vi.fn().mockReturnValue([]),
+  };
+}
+
+function createInteractiveSession(): InteractiveSession {
+  return new InteractiveSession({
+    session: createMockRuntimeSession() as never,
+    commandModules: [createRewindCommandModule()],
+  });
+}
+
+describe('createRewindCommandModule', () => {
+  it('contributes write-safe rewind metadata and executable command', () => {
+    const module = createRewindCommandModule();
+    const commands = module.commandSources?.flatMap((source) => source.getCommands()) ?? [];
+
+    expect(module.name).toBe('agent-command-rewind');
+    expect(commands.map((command) => command.name)).toEqual(['rewind']);
+    expect(commands[0]?.source).toBe('rewind');
+    expect(commands[0]?.modelInvocable).toBe(false);
+    expect(commands[0]?.safety).toBe('write');
+    expect(commands[0]?.subcommands?.map((command) => command.name)).toEqual([
+      'list',
+      'inspect',
+      'restore',
+      'code',
+      'rollback',
+    ]);
+    expect(module.systemCommands?.map((command) => command.name)).toEqual(['rewind']);
+    expect(module.systemCommands?.[0]?.userInvocable).toBe(true);
+  });
+
+  it('provides a stable command source', () => {
+    const source = new RewindCommandSource();
+
+    expect(source.name).toBe('rewind');
+    expect(source.getCommands()).toHaveLength(1);
+  });
+});
+
+describe('executeRewindCommand', () => {
+  it('lists edit checkpoints', async () => {
+    const session = createInteractiveSession();
+    vi.spyOn(session, 'listEditCheckpoints').mockReturnValue([createCheckpoint()]);
+
+    const result = await session.executeCommand('rewind', 'list');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('turn-0001');
+    expect(result?.data?.count).toBe(1);
+  });
+
+  it('shows an empty checkpoint list', async () => {
+    const session = createInteractiveSession();
+    vi.spyOn(session, 'listEditCheckpoints').mockReturnValue([]);
+
+    const result = await session.executeCommand('rewind', '');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('(no edit checkpoints)');
+    expect(result?.data?.count).toBe(0);
+  });
+
+  it('inspects captured files and rollback plans', async () => {
+    const session = createInteractiveSession();
+    const inspectEditCheckpoint = vi
+      .spyOn(session, 'inspectEditCheckpoint')
+      .mockReturnValue(createInspection());
+
+    const result = await session.executeCommand('rewind', 'inspect turn-0001');
+
+    expect(result?.success).toBe(true);
+    expect(inspectEditCheckpoint).toHaveBeenCalledWith('turn-0001');
+    expect(result?.message).toContain('Captured files:');
+    expect(result?.message).toContain('example.ts');
+    expect(result?.message).toContain('Rollback through checkpoint');
+    expect(result?.data?.inspection).toEqual(createInspection());
+  });
+
+  it('delegates restore through session.executeCommand', async () => {
+    const session = createInteractiveSession();
+    const restoreEditCheckpoint = vi
+      .spyOn(session, 'restoreEditCheckpoint')
+      .mockResolvedValue(createRestoreResult());
+
+    const result = await session.executeCommand('rewind', 'restore turn-0001');
+
+    expect(result?.success).toBe(true);
+    expect(restoreEditCheckpoint).toHaveBeenCalledWith('turn-0001');
+    expect(result?.message).toContain('Restored code to turn-0001.');
+    expect(result?.data?.restoredFileCount).toBe(3);
+  });
+
+  it('treats code as a restore alias', async () => {
+    const session = createInteractiveSession();
+    const restoreEditCheckpoint = vi
+      .spyOn(session, 'restoreEditCheckpoint')
+      .mockResolvedValue(createRestoreResult());
+
+    const result = await session.executeCommand('rewind', 'code turn-0001');
+
+    expect(result?.success).toBe(true);
+    expect(restoreEditCheckpoint).toHaveBeenCalledWith('turn-0001');
+  });
+
+  it('delegates rollback through session.executeCommand', async () => {
+    const session = createInteractiveSession();
+    const rollbackEditCheckpoint = vi
+      .spyOn(session, 'rollbackEditCheckpoint')
+      .mockResolvedValue(
+        createRestoreResult({ restoredCheckpointCount: 1, removedCheckpointCount: 1 }),
+      );
+
+    const result = await session.executeCommand('rewind', 'rollback turn-0001');
+
+    expect(result?.success).toBe(true);
+    expect(rollbackEditCheckpoint).toHaveBeenCalledWith('turn-0001');
+    expect(result?.message).toContain('Rolled back code through turn-0001.');
+  });
+
+  it('returns usage for invalid arguments without mutating state', async () => {
+    const session = createInteractiveSession();
+    const restoreEditCheckpoint = vi.spyOn(session, 'restoreEditCheckpoint');
+    const rollbackEditCheckpoint = vi.spyOn(session, 'rollbackEditCheckpoint');
+
+    const result = await executeRewindCommand(session, 'restore');
+    const unknownResult = await executeRewindCommand(session, 'unknown');
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('Usage: rewind');
+    expect(unknownResult.success).toBe(false);
+    expect(restoreEditCheckpoint).not.toHaveBeenCalled();
+    expect(rollbackEditCheckpoint).not.toHaveBeenCalled();
+  });
+
+  it('returns checkpoint API errors as command failures', async () => {
+    const session = createInteractiveSession();
+    vi.spyOn(session, 'restoreEditCheckpoint').mockRejectedValue(
+      new Error('Unknown edit checkpoint'),
+    );
+
+    const result = await session.executeCommand('rewind', 'restore missing');
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toBe('Unknown edit checkpoint');
+  });
+});

package/src/rewind/index.ts

@@ -0,0 +1,2 @@
+export { createRewindCommandModule, RewindCommandSource } from './rewind-command-module.js';
+export { executeRewindCommand } from './rewind-command.js';

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

@@ -0,0 +1,57 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import {
+  REWIND_COMMAND_ARGUMENT_HINT,
+  REWIND_COMMAND_DESCRIPTION,
+  buildRewindCommandSubcommands,
+} from '@robota-sdk/agent-framework';
+import { executeRewindCommand } from './rewind-command.js';
+
+export function createRewindCommandEntry(): ICommand {
+  return {
+    name: 'rewind',
+    displayName: 'Rewind History',
+    description: REWIND_COMMAND_DESCRIPTION,
+    source: 'rewind',
+    argumentHint: REWIND_COMMAND_ARGUMENT_HINT,
+    modelInvocable: false,
+    safety: 'write',
+    subcommands: buildRewindCommandSubcommands(),
+  };
+}
+
+function createRewindSystemCommand(): ISystemCommand {
+  const entry = createRewindCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    argumentHint: entry.argumentHint,
+    userInvocable: true,
+    modelInvocable: false,
+    safety: 'write',
+    subcommands: entry.subcommands,
+    execute: executeRewindCommand,
+  };
+}
+
+export class RewindCommandSource implements ICommandSource {
+  readonly name = 'rewind';
+
+  getCommands(): ICommand[] {
+    return [createRewindCommandEntry()];
+  }
+}
+
+export function createRewindCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-rewind',
+    commandSources: [new RewindCommandSource()],
+    systemCommands: [createRewindSystemCommand()],
+  };
+}

package/src/rewind/rewind-command.ts

@@ -0,0 +1,184 @@
+import type {
+  ICommandHostContext,
+  ICommandResult,
+  IEditCheckpointInspection,
+  IEditCheckpointRestoreResult,
+  IEditCheckpointSummary,
+} from '@robota-sdk/agent-framework';
+import {
+  inspectCommandEditCheckpoint,
+  listCommandEditCheckpoints,
+  restoreCommandEditCheckpoint,
+  rollbackCommandEditCheckpoint,
+} from '@robota-sdk/agent-framework';
+
+const SUBCOMMAND_INDEX = 0;
+const CHECKPOINT_ID_INDEX = 1;
+const PROMPT_PREVIEW_LENGTH = 120;
+const ELLIPSIS_LENGTH = 3;
+
+function usage(): ICommandResult {
+  return {
+    message:
+      'Usage: rewind [list] | rewind inspect <checkpoint-id> | rewind restore <checkpoint-id> | rewind code <checkpoint-id> | rewind rollback <checkpoint-id>',
+    success: false,
+  };
+}
+
+function formatPrompt(prompt: string): string {
+  const compact = prompt.replace(/\s+/g, ' ').trim();
+  if (compact.length <= PROMPT_PREVIEW_LENGTH) return compact;
+  return `${compact.slice(0, PROMPT_PREVIEW_LENGTH - ELLIPSIS_LENGTH)}...`;
+}
+
+function formatList(checkpoints: readonly IEditCheckpointSummary[]): ICommandResult {
+  const lines =
+    checkpoints.length > 0
+      ? checkpoints.map(
+          (checkpoint) =>
+            `- ${checkpoint.id} files=${checkpoint.fileCount} ${checkpoint.createdAt} ${formatPrompt(
+              checkpoint.prompt,
+            )}`,
+        )
+      : ['(no edit checkpoints)'];
+
+  return {
+    message: ['Edit checkpoints:', ...lines].join('\n'),
+    success: true,
+    data: { count: checkpoints.length, checkpoints: [...checkpoints] },
+  };
+}
+
+function formatCheckpointIds(ids: readonly string[]): string {
+  return ids.length > 0 ? ids.join(', ') : '(none)';
+}
+
+function formatInspection(inspection: IEditCheckpointInspection): ICommandResult {
+  const fileLines =
+    inspection.capturedFiles.length > 0
+      ? inspection.capturedFiles.map((file) => {
+          const size =
+            file.snapshotSizeBytes === undefined ? '' : ` size=${file.snapshotSizeBytes}B`;
+          return `- ${file.relativePath} action=${file.restoreAction} snapshot=${String(
+            file.snapshotAvailable,
+          )}${size}`;
+        })
+      : ['(no files captured)'];
+
+  return {
+    message: [
+      `Checkpoint ${inspection.target.id}`,
+      `Prompt: ${formatPrompt(inspection.target.prompt)}`,
+      'Captured files:',
+      ...fileLines,
+      `Restore later checkpoints: files=${inspection.restoreToCheckpoint.fileCount} checkpoints=${formatCheckpointIds(
+        inspection.restoreToCheckpoint.checkpointIds,
+      )}`,
+      `Rollback through checkpoint: files=${inspection.rollbackThroughCheckpoint.fileCount} checkpoints=${formatCheckpointIds(
+        inspection.rollbackThroughCheckpoint.checkpointIds,
+      )}`,
+    ].join('\n'),
+    success: true,
+    data: { inspection },
+  };
+}
+
+function formatRestoreResult(result: IEditCheckpointRestoreResult): ICommandResult {
+  return {
+    message: [
+      `Restored code to ${result.target.id}.`,
+      `Restored files: ${result.restoredFileCount}`,
+      `Rolled back checkpoints: ${result.restoredCheckpointCount}`,
+    ].join('\n'),
+    success: true,
+    data: {
+      target: result.target,
+      restoredCheckpointCount: result.restoredCheckpointCount,
+      restoredFileCount: result.restoredFileCount,
+      removedCheckpointCount: result.removedCheckpointCount,
+    },
+  };
+}
+
+function formatRollbackResult(result: IEditCheckpointRestoreResult): ICommandResult {
+  return {
+    message: [
+      `Rolled back code through ${result.target.id}.`,
+      `Restored files: ${result.restoredFileCount}`,
+      `Removed checkpoints: ${result.removedCheckpointCount}`,
+    ].join('\n'),
+    success: true,
+    data: {
+      target: result.target,
+      restoredCheckpointCount: result.restoredCheckpointCount,
+      restoredFileCount: result.restoredFileCount,
+      removedCheckpointCount: result.removedCheckpointCount,
+    },
+  };
+}
+
+function formatError(error: Error | string): ICommandResult {
+  return {
+    message: error instanceof Error ? error.message : String(error),
+    success: false,
+  };
+}
+
+function inspect(context: ICommandHostContext, checkpointId: string | undefined): ICommandResult {
+  if (!checkpointId) return usage();
+  try {
+    return formatInspection(inspectCommandEditCheckpoint(context, checkpointId));
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
+async function restore(
+  context: ICommandHostContext,
+  checkpointId: string | undefined,
+): Promise<ICommandResult> {
+  if (!checkpointId) return usage();
+  try {
+    return formatRestoreResult(await restoreCommandEditCheckpoint(context, checkpointId));
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
+async function rollback(
+  context: ICommandHostContext,
+  checkpointId: string | undefined,
+): Promise<ICommandResult> {
+  if (!checkpointId) return usage();
+  try {
+    return formatRollbackResult(await rollbackCommandEditCheckpoint(context, checkpointId));
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
+export async function executeRewindCommand(
+  context: ICommandHostContext,
+  rawArgs: string,
+): Promise<ICommandResult> {
+  const args = rawArgs.trim().split(/\s+/).filter(Boolean);
+  const subcommand = args[SUBCOMMAND_INDEX] ?? 'list';
+
+  if (subcommand === 'list') {
+    return formatList(listCommandEditCheckpoints(context));
+  }
+
+  if (subcommand === 'inspect') {
+    return inspect(context, args[CHECKPOINT_ID_INDEX]);
+  }
+
+  if (subcommand === 'restore' || subcommand === 'code') {
+    return restore(context, args[CHECKPOINT_ID_INDEX]);
+  }
+
+  if (subcommand === 'rollback') {
+    return rollback(context, args[CHECKPOINT_ID_INDEX]);
+  }
+
+  return usage();
+}