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

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

@@ -0,0 +1,287 @@
+import { afterEach, 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(commandProductVocabulary?: { cliName: string; displayName: string }): InteractiveSession {
+  return new InteractiveSession({
+    session: createMockRuntimeSession() as never,
+    commandModules: [createRewindCommandModule()],
+    commandProductVocabulary,
+  });
+}
+
+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',
+      'fork',
+      'switch',
+      'branches',
+    ]);
+    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.');
+  });
+
+  // SELFHOST-007 TC-05: branching subcommands route through the host context.
+  it('delegates fork through session.executeCommand (non-destructive)', async () => {
+    const session = createInteractiveSession();
+    const forkCheckpointBranch = vi
+      .spyOn(session, 'forkCheckpointBranch')
+      .mockResolvedValue(createRestoreResult());
+
+    const result = await session.executeCommand('rewind', 'fork turn-0001');
+
+    expect(result?.success).toBe(true);
+    expect(forkCheckpointBranch).toHaveBeenCalledWith('turn-0001');
+    expect(result?.message).toContain('Forked a new branch from turn-0001');
+  });
+
+  it('delegates switch through session.executeCommand', async () => {
+    const session = createInteractiveSession();
+    const switchCheckpointBranch = vi.spyOn(session, 'switchCheckpointBranch').mockReturnValue();
+
+    const result = await session.executeCommand('rewind', 'switch turn-0002');
+
+    expect(result?.success).toBe(true);
+    expect(switchCheckpointBranch).toHaveBeenCalledWith('turn-0002');
+    expect(result?.message).toContain('Switched to checkpoint branch turn-0002.');
+  });
+
+  it('lists branch tips via the branches subcommand', async () => {
+    const session = createInteractiveSession();
+    vi.spyOn(session, 'listCheckpointBranches').mockReturnValue(['turn-0003', 'turn-0005']);
+
+    const result = await session.executeCommand('rewind', 'branches');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toContain('turn-0003');
+    expect(result?.message).toContain('turn-0005');
+    expect(result?.data?.branches).toEqual(['turn-0003', 'turn-0005']);
+  });
+
+  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');
+  });
+
+  describe('in a session built without a checkpoint store', () => {
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('tells a restricted workspace to trust it, for every subcommand', async () => {
+      vi.spyOn(process, 'platform', 'get').mockReturnValue('linux');
+      const session = createInteractiveSession({ cliName: 'test-agent', displayName: 'Test Agent' });
+
+      for (const args of ['', 'list', 'inspect turn-0001', 'restore turn-0001', 'branches']) {
+        const result = await session.executeCommand('rewind', args);
+        expect(result?.success).toBe(false);
+        expect(result?.message).toBe(
+          'Edit checkpoints need a trusted workspace: run test-agent trust --yes, then restart test-agent.',
+        );
+      }
+    });
+
+    it('says why on a host that cannot prove a project write is safe, without naming trust', async () => {
+      vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin');
+      const session = createInteractiveSession();
+
+      const result = await session.executeCommand('rewind', 'list');
+
+      expect(result?.success).toBe(false);
+      // #3289 §3: plain words naming the feature ("Rewind"), not the internal write-containment reason.
+      expect(result?.message).toBe("Rewind isn't available on this computer yet.");
+      expect(result?.message).not.toContain('trust');
+    });
+  });
+});

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,56 @@
+import {
+  REWIND_COMMAND_ARGUMENT_HINT,
+  REWIND_COMMAND_DESCRIPTION,
+  buildRewindCommandSubcommands,
+} from '@robota-sdk/agent-framework';
+
+import { executeRewindCommand } from './rewind-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createRewindCommandEntry(): ICommand {
+  return {
+    name: 'rewind',
+    displayName: 'Rewind History',
+    description: REWIND_COMMAND_DESCRIPTION,
+    source: 'rewind',
+    argumentHint: REWIND_COMMAND_ARGUMENT_HINT,
+    // User-only: rewrites the user's history and files; the user decides what to undo.
+    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,279 @@
+import {
+  EditCheckpointsUnavailableError,
+  inspectCommandEditCheckpoint,
+  listCommandEditCheckpoints,
+  restoreCommandEditCheckpoint,
+  rollbackCommandEditCheckpoint,
+  forkCommandEditCheckpoint,
+  switchCommandEditCheckpointBranch,
+  listCommandEditCheckpointBranches,
+} from '@robota-sdk/agent-framework';
+
+import type {
+  ICommandHostCheckpoints,
+  IEditCheckpointInspection,
+  IEditCheckpointRestoreResult,
+  IEditCheckpointSummary,
+} from '@robota-sdk/agent-framework';
+import type { ICommandProductVocabulary } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+type TRewindCommandContext = ICommandHostCheckpoints & {
+  getCommandProductVocabulary?(): ICommandProductVocabulary | undefined;
+};
+
+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,
+    },
+  };
+}
+
+/** A restricted workspace is the one case the user fixes with a command; the rest say why. */
+function unavailableMessage(error: EditCheckpointsUnavailableError, cliName?: string): string {
+  if (error.reason !== 'restricted-workspace') return error.message;
+  return cliName === undefined
+    ? 'Edit checkpoints need a trusted workspace. Trust it from a terminal, then restart the session.'
+    : `Edit checkpoints need a trusted workspace: run ${cliName} trust --yes, then restart ${cliName}.`;
+}
+
+function formatError(error: Error | string, cliName?: string): ICommandResult {
+  return {
+    message:
+      error instanceof EditCheckpointsUnavailableError
+        ? unavailableMessage(error, cliName)
+        : error instanceof Error
+          ? error.message
+          : String(error),
+    success: false,
+  };
+}
+
+function list(context: TRewindCommandContext): ICommandResult {
+  try {
+    return formatList(listCommandEditCheckpoints(context));
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
+  }
+}
+
+function inspect(
+  context: TRewindCommandContext,
+  checkpointId: string | undefined,
+): ICommandResult {
+  if (!checkpointId) return usage();
+  try {
+    return formatInspection(inspectCommandEditCheckpoint(context, checkpointId));
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
+  }
+}
+
+async function restore(
+  context: TRewindCommandContext,
+  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), context.getCommandProductVocabulary?.()?.cliName);
+  }
+}
+
+async function rollback(
+  context: TRewindCommandContext,
+  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), context.getCommandProductVocabulary?.()?.cliName);
+  }
+}
+
+// SELFHOST-007: branching time-travel handlers.
+async function fork(
+  context: TRewindCommandContext,
+  checkpointId: string | undefined,
+): Promise<ICommandResult> {
+  if (!checkpointId) return usage();
+  try {
+    const result = await forkCommandEditCheckpoint(context, checkpointId);
+    return {
+      message: [
+        `Forked a new branch from ${result.target.id} (the previous future is preserved).`,
+        `Restored files: ${result.restoredFileCount}`,
+      ].join('\n'),
+      success: true,
+      data: { target: result.target, restoredFileCount: result.restoredFileCount },
+    };
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
+  }
+}
+
+function switchBranch(
+  context: TRewindCommandContext,
+  checkpointId: string | undefined,
+): ICommandResult {
+  if (!checkpointId) return usage();
+  try {
+    switchCommandEditCheckpointBranch(context, checkpointId);
+    return { message: `Switched to checkpoint branch ${checkpointId}.`, success: true };
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
+  }
+}
+
+function branches(context: TRewindCommandContext): ICommandResult {
+  try {
+    const tips = listCommandEditCheckpointBranches(context);
+    return {
+      message:
+        tips.length === 0
+          ? 'No checkpoint branches yet.'
+          : `Branch tips:\n${tips.map((id) => `- ${id}`).join('\n')}`,
+      success: true,
+      data: { branches: tips },
+    };
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error), context.getCommandProductVocabulary?.()?.cliName);
+  }
+}
+
+export async function executeRewindCommand(
+  context: TRewindCommandContext,
+  rawArgs: string,
+): Promise<ICommandResult> {
+  const args = rawArgs.trim().split(/\s+/).filter(Boolean);
+  const subcommand = args[SUBCOMMAND_INDEX] ?? 'list';
+
+  if (subcommand === 'list') {
+    return list(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]);
+  }
+
+  // SELFHOST-007: branching time-travel subcommands.
+  if (subcommand === 'fork') {
+    return fork(context, args[CHECKPOINT_ID_INDEX]);
+  }
+  if (subcommand === 'switch') {
+    return switchBranch(context, args[CHECKPOINT_ID_INDEX]);
+  }
+  if (subcommand === 'branches') {
+    return branches(context);
+  }
+
+  return usage();
+}