@robota-sdk/agent-command 3.0.0-beta.78 → 3.0.0-beta.81

package/src/remote-control/__tests__/remote-control-command.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'vitest';
+
+import { createRemoteControlCommandEntry } from '../remote-control-command-module.js';
+import { executeRemoteControlCommand } from '../remote-control-command.js';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import type {
+  ICommandRemoteControlAdapter,
+  TRemoteControlStatus,
+} from '@robota-sdk/agent-framework';
+
+/**
+ * REMOTE-008 — `/remote-control` command: a declarative trigger (enable/stop return host actions) + a
+ * status read over the injected `remoteControl` adapter.
+ */
+
+function ctx(status?: TRemoteControlStatus) {
+  const adapter: ICommandRemoteControlAdapter | undefined =
+    status === undefined ? undefined : { getStatus: () => status };
+  return createTestCommandHost({
+    overrides: {
+      getCommandHostAdapters: () => (adapter ? { remoteControl: adapter } : {}),
+    },
+  });
+}
+
+describe('executeRemoteControlCommand (REMOTE-008)', () => {
+  it('default (no args) requests enable via a host effect (no transport touched by the command)', () => {
+    const result = executeRemoteControlCommand(ctx(), '');
+    expect(result.success).toBe(true);
+    expect(result.hostActions).toEqual([{ type: 'remote-control-enable' }]);
+  });
+
+  it('`enable` / `on` also request enable', () => {
+    expect(executeRemoteControlCommand(ctx(), 'enable').hostActions).toEqual([
+      { type: 'remote-control-enable' },
+    ]);
+    expect(executeRemoteControlCommand(ctx(), 'ON').hostActions).toEqual([
+      { type: 'remote-control-enable' },
+    ]);
+  });
+
+  it('`stop` / `off` request the stop host action', () => {
+    expect(executeRemoteControlCommand(ctx(), 'stop').hostActions).toEqual([
+      { type: 'remote-control-stop' },
+    ]);
+    expect(executeRemoteControlCommand(ctx(), 'off').hostActions).toEqual([
+      { type: 'remote-control-stop' },
+    ]);
+  });
+
+  it('`status` reads the adapter and reports the awaiting-pairing URL', () => {
+    const result = executeRemoteControlCommand(
+      ctx({ state: 'awaiting-pairing', pairingUrl: 'https://x/#r=a&s=b' }),
+      'status',
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('https://x/#r=a&s=b');
+    expect(result.hostActions).toBeUndefined(); // status is read-only, no action
+  });
+
+  it('`status` with no relay reports the missing-relay guidance', () => {
+    const result = executeRemoteControlCommand(ctx({ state: 'no-relay' }), 'status');
+    expect(result.message).toMatch(/relayUrl/);
+  });
+
+  it('`status` with no adapter reports unavailability (never throws)', () => {
+    const result = executeRemoteControlCommand(ctx(), 'status');
+    expect(result.success).toBe(true);
+    expect(result.message).toMatch(/not available/i);
+  });
+
+  it('an unknown argument is a usage error (no effect)', () => {
+    const result = executeRemoteControlCommand(ctx(), 'frobnicate');
+    expect(result.success).toBe(false);
+    expect(result.hostActions).toBeUndefined();
+  });
+
+  // REMOTE-012 E3 — trusted-device management verbs.
+  function e3ctx(over: Partial<ICommandRemoteControlAdapter>) {
+    const adapter: ICommandRemoteControlAdapter = { getStatus: () => ({ state: 'off' }), ...over };
+    return createTestCommandHost({
+      overrides: { getCommandHostAdapters: () => ({ remoteControl: adapter }) },
+    });
+  }
+
+  it('`devices` lists enrolled trusted devices', () => {
+    const result = executeRemoteControlCommand(
+      e3ctx({
+        listDevices: () => [
+          { deviceId: 'AbC-123', label: 'phone', lastSeenAt: '2026-07-11T00:00:00Z' },
+        ],
+      }),
+      'devices',
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('AbC-123');
+    expect(result.message).toContain('phone');
+  });
+
+  it('`devices` with none enrolled says so', () => {
+    const result = executeRemoteControlCommand(e3ctx({ listDevices: () => [] }), 'devices');
+    expect(result.message).toMatch(/no trusted devices/i);
+  });
+
+  it('`revoke <id>` removes a device (case-preserving id) and reports it', () => {
+    let revoked: string | undefined;
+    const result = executeRemoteControlCommand(
+      e3ctx({
+        revokeDevice: (id) => {
+          revoked = id;
+          return true;
+        },
+      }),
+      'revoke AbC-123',
+    );
+    expect(revoked).toBe('AbC-123'); // NOT lowercased
+    expect(result.success).toBe(true);
+    expect(result.message).toMatch(/revoked/i);
+  });
+
+  it('`revoke` of an unknown id is a failure notice', () => {
+    const result = executeRemoteControlCommand(
+      e3ctx({ revokeDevice: () => false }),
+      'revoke ghost',
+    );
+    expect(result.success).toBe(false);
+    expect(result.message).toMatch(/no trusted device/i);
+  });
+
+  it('`revoke` with no id is a usage error', () => {
+    const result = executeRemoteControlCommand(e3ctx({ revokeDevice: () => true }), 'revoke');
+    expect(result.success).toBe(false);
+    expect(result.message).toMatch(/usage/i);
+  });
+
+  it('`status` names where the host key is kept', () => {
+    const result = executeRemoteControlCommand(
+      e3ctx({
+        describeKeyStorage: () =>
+          'owner-only file in /h/.robota/credentials (OS keychain unavailable: absent)',
+      }),
+      'status',
+    );
+    expect(result.message).toContain(
+      'Host key storage: owner-only file in /h/.robota/credentials (OS keychain unavailable: absent)',
+    );
+  });
+
+  it('`status` says the key storage is still to be chosen before any key was needed', () => {
+    const result = executeRemoteControlCommand(
+      e3ctx({ describeKeyStorage: () => undefined }),
+      'status',
+    );
+    expect(result.message).toMatch(/Host key storage: chosen when remote control is first enabled/);
+  });
+
+  // Pairing and trust are the local operator's. A surface that is already connected must not be able
+  // to mint a new pairing link, read one, or change which devices are trusted.
+  function remoteCtx(over: Partial<ICommandRemoteControlAdapter> = {}) {
+    const adapter: ICommandRemoteControlAdapter = { getStatus: () => ({ state: 'off' }), ...over };
+    return createTestCommandHost({
+      overrides: {
+        getCommandHostAdapters: () => ({ remoteControl: adapter }),
+        getCommandInvocationSource: () => 'remote',
+      },
+    });
+  }
+
+  it.each(['', 'enable', 'on'])(
+    'refuses `%s` from a remote surface without requesting enable',
+    (verb) => {
+      const result = executeRemoteControlCommand(remoteCtx(), verb);
+      expect(result.success).toBe(false);
+      expect(result.hostActions).toBeUndefined();
+      expect(result.message).toMatch(/operator at this terminal/);
+    },
+  );
+
+  it('never shows a remote surface the pairing link', () => {
+    const result = executeRemoteControlCommand(
+      remoteCtx({
+        getStatus: () => ({ state: 'awaiting-pairing', pairingUrl: 'https://x/#r=a&s=b' }),
+      }),
+      'status',
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).not.toContain('https://x/#r=a&s=b');
+    expect(result.message).not.toContain('#r=');
+    expect(result.message).toMatch(/waiting for a device to pair/);
+  });
+
+  it('refuses `revoke` from a remote surface without touching the trusted devices', () => {
+    const revokeDevice = (): boolean => {
+      throw new Error('must not be called');
+    };
+    const result = executeRemoteControlCommand(remoteCtx({ revokeDevice }), 'revoke AbC-123');
+    expect(result.success).toBe(false);
+    expect(result.message).toMatch(/operator at this terminal/);
+  });
+
+  it('still lets a remote surface stop remote control and read the other states', () => {
+    expect(executeRemoteControlCommand(remoteCtx(), 'stop').hostActions).toEqual([
+      { type: 'remote-control-stop' },
+    ]);
+    const paired = executeRemoteControlCommand(
+      remoteCtx({ getStatus: () => ({ state: 'paired' }) }),
+      'status',
+    );
+    expect(paired.message).toMatch(/a device is paired/);
+  });
+
+  it('stays user-only for the model', () => {
+    expect(createRemoteControlCommandEntry().modelInvocable).toBe(false);
+  });
+});

package/src/remote-control/index.ts

@@ -0,0 +1,8 @@
+// @robota-sdk/agent-command-remote-control
+
+export {
+  createRemoteControlCommandModule,
+  createRemoteControlCommandEntry,
+  RemoteControlCommandSource,
+} from './remote-control-command-module.js';
+export { executeRemoteControlCommand } from './remote-control-command.js';

package/src/remote-control/remote-control-command-module.ts

@@ -0,0 +1,61 @@
+import { executeRemoteControlCommand } from './remote-control-command.js';
+import { createSystemCommandFromEntry } from '../command-module-utils.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createRemoteControlCommandEntry(): ICommand {
+  return {
+    name: 'remote-control',
+    displayName: 'Remote control',
+    description:
+      'Enable P2P remote control (pair a device to co-drive this session), or check status. Pairing and revoking run only for the operator at the host terminal; a connected surface can stop remote control and read its status, without the pairing link.',
+    source: 'remote-control',
+    // User-only: pairing and revoking devices are trust decisions. The command also refuses them when
+    // they come from a connected surface rather than the operator at this terminal.
+    modelInvocable: false,
+    userInvocable: true,
+    argumentHint: '[enable|stop|status|devices|revoke <device-id>]',
+    subcommands: [
+      { name: 'status', description: 'Show remote-control status', source: 'remote-control' },
+      { name: 'devices', description: 'List trusted devices', source: 'remote-control' },
+      {
+        name: 'enable',
+        description: 'Enable remote control and pair a device',
+        source: 'remote-control',
+      },
+      { name: 'stop', description: 'Stop remote control', source: 'remote-control' },
+      {
+        name: 'revoke',
+        description: 'Revoke a trusted device',
+        source: 'remote-control',
+        argumentHint: '<device-id>',
+      },
+    ],
+  };
+}
+
+function createRemoteControlSystemCommand(): ISystemCommand {
+  const entry = createRemoteControlCommandEntry();
+  return createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: (context, args) => executeRemoteControlCommand(context, args),
+  });
+}
+
+export class RemoteControlCommandSource implements ICommandSource {
+  readonly name = 'remote-control';
+
+  getCommands(): ICommand[] {
+    return [createRemoteControlCommandEntry()];
+  }
+}
+
+export function createRemoteControlCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-remote-control',
+    commandSources: [new RemoteControlCommandSource()],
+    systemCommands: [createRemoteControlSystemCommand()],
+  };
+}

package/src/remote-control/remote-control-command.ts

@@ -0,0 +1,138 @@
+import type {
+  ICommandHostAdapterAccess,
+  ICommandHostWorkspace,
+  TRemoteControlStatus,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+/**
+ * `/remote-control` (REMOTE-008) — enable/stop P2P remote control and report status.
+ *
+ * The command is a declarative trigger: `enable` and `stop` return typed HOST ACTIONS
+ * (`remote-control-enable` / `remote-control-stop`) executed by the session via the composition-root
+ * adapter (commands never construct transports). `status` reads the injected
+ * `ICommandHostAdapters.remoteControl.getStatus()` view — absent ⇒ the feature is unavailable in this host.
+ *
+ * Pairing and trust belong to the operator at this terminal. A surface that is already connected
+ * may stop remote control and read its state, but it cannot mint a pairing link, read the one on
+ * offer, or revoke a trusted device: otherwise one connected surface could admit the next.
+ */
+
+const OPERATOR_ONLY =
+  'only the operator at this terminal can do this; a connected surface cannot pair, enroll or revoke devices. ' +
+  'Run `/remote-control` on the host terminal.';
+
+function formatStatus(
+  status: TRemoteControlStatus | undefined,
+  showPairingLink: boolean,
+): ICommandResult {
+  if (!status) {
+    return { message: 'Remote control is not available in this environment.', success: true };
+  }
+  switch (status.state) {
+    case 'off':
+      return {
+        message: 'Remote control is off. Use `/remote-control` to enable it.',
+        success: true,
+      };
+    case 'no-relay':
+      return {
+        message:
+          'Remote control is unavailable: no signaling relay is configured ' +
+          '(set `transports.webrtc.options.relayUrl`).',
+        success: true,
+      };
+    case 'awaiting-pairing':
+      return {
+        message: showPairingLink
+          ? `Remote control is waiting for a device to pair.\nOpen: ${status.pairingUrl}`
+          : 'Remote control is waiting for a device to pair. The pairing link is shown only on the host terminal.',
+        success: true,
+      };
+    case 'paired':
+      return { message: 'Remote control is active — a device is paired.', success: true };
+    default:
+      return { message: 'Remote control status is unknown.', success: true };
+  }
+}
+
+export function executeRemoteControlCommand(
+  context: ICommandHostAdapterAccess & Pick<ICommandHostWorkspace, 'getCommandInvocationSource'>,
+  args: string,
+): ICommandResult {
+  const operator = context.getCommandInvocationSource() === 'user';
+  const trimmed = args.trim();
+  // Split into a lowercased verb + the original-case remainder (a deviceId is case-sensitive base64url).
+  const spaceAt = trimmed.indexOf(' ');
+  const verb = (spaceAt === -1 ? trimmed : trimmed.slice(0, spaceAt)).toLowerCase();
+  const rest = spaceAt === -1 ? '' : trimmed.slice(spaceAt + 1).trim();
+
+  if (verb === 'status') {
+    const adapter = context.getCommandHostAdapters?.().remoteControl;
+    const result = formatStatus(adapter?.getStatus(), operator);
+    if (!adapter?.describeKeyStorage) return result;
+    const storage = adapter.describeKeyStorage() ?? 'chosen when remote control is first enabled';
+    return { ...result, message: `${result.message}\nHost key storage: ${storage}` };
+  }
+
+  if (verb === 'devices') {
+    const adapter = context.getCommandHostAdapters?.().remoteControl;
+    const devices = adapter?.listDevices?.();
+    if (!devices) {
+      return {
+        message: 'Trusted-device reconnect is not available in this environment.',
+        success: true,
+      };
+    }
+    if (devices.length === 0) {
+      return { message: 'No trusted devices are enrolled yet.', success: true };
+    }
+    const lines = devices.map((d) => `  ${d.deviceId}  ${d.label}  (last seen ${d.lastSeenAt})`);
+    return { message: `Trusted devices:\n${lines.join('\n')}`, success: true };
+  }
+
+  if (verb === 'revoke') {
+    if (!operator) {
+      return { message: `\`/remote-control revoke\`: ${OPERATOR_ONLY}`, success: false };
+    }
+    if (!rest) {
+      return { message: 'Usage: /remote-control revoke <deviceId>', success: false };
+    }
+    const adapter = context.getCommandHostAdapters?.().remoteControl;
+    if (!adapter?.revokeDevice) {
+      return {
+        message: 'Trusted-device reconnect is not available in this environment.',
+        success: true,
+      };
+    }
+    const removed = adapter.revokeDevice(rest);
+    return removed
+      ? { message: `Revoked trusted device ${rest}. It must re-pair to reconnect.`, success: true }
+      : { message: `No trusted device with id ${rest}.`, success: false };
+  }
+
+  if (verb === 'stop' || verb === 'off') {
+    return {
+      message: 'Stopping remote control...',
+      success: true,
+      hostActions: [{ type: 'remote-control-stop' as const }],
+    };
+  }
+
+  // Default (empty / `enable` / `on`): request enable. The host reports the pairing QR/link.
+  if (verb === '' || verb === 'enable' || verb === 'on') {
+    if (!operator) {
+      return { message: `\`/remote-control enable\`: ${OPERATOR_ONLY}`, success: false };
+    }
+    return {
+      message: 'Enabling remote control...',
+      success: true,
+      hostActions: [{ type: 'remote-control-enable' as const }],
+    };
+  }
+
+  return {
+    message: `Unknown argument "${verb}". Usage: /remote-control [enable|stop|status|devices|revoke <id>]`,
+    success: false,
+  };
+}

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
 import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
 import {
   createResetCommandEntry,
@@ -7,7 +7,7 @@ import {
   executeResetCommand,
 } from '../index.js';
 
-const COMMAND_CONTEXT = {} as ICommandHostContext;
+const COMMAND_CONTEXT = createTestCommandHost();
 
 describe('createResetCommandModule', () => {
   it('provides reset metadata and a user-only executable command from one module owner', () => {
@@ -36,13 +36,13 @@ describe('createResetCommandModule', () => {
   });
 
   it('emits a typed settings reset effect without host file I/O', () => {
-    const result = executeResetCommand(COMMAND_CONTEXT, '');
+    const result = executeResetCommand();
 
     expect(result).toEqual({
       success: true,
       message: 'Reset requested.',
       data: { resetRequested: true },
-      effects: [{ type: 'settings-reset-requested' }],
+      hostActions: [{ type: 'settings-reset' }],
     });
   });
 
@@ -57,7 +57,7 @@ describe('createResetCommandModule', () => {
       success: true,
       message: 'Reset requested.',
       data: { resetRequested: true },
-      effects: [{ type: 'settings-reset-requested' }],
+      hostActions: [{ type: 'settings-reset' }],
     });
   });
 });

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

@@ -1,7 +1,7 @@
 import { executeResetCommand } from './reset-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 const RESET_COMMAND_DESCRIPTION = 'Delete settings';
 
@@ -11,6 +11,7 @@ export function createResetCommandEntry(): ICommand {
     displayName: 'Reset Settings',
     description: RESET_COMMAND_DESCRIPTION,
     source: 'reset',
+    // User-only: discards the user's settings.
     modelInvocable: false,
   };
 }

package/src/reset/reset-command.ts

@@ -1,11 +1,10 @@
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
-export function executeResetCommand(_context: ICommandHostContext, _args: string): ICommandResult {
+export function executeResetCommand(): ICommandResult {
   return {
     success: true,
     message: 'Reset requested.',
     data: { resetRequested: true },
-    effects: [{ type: 'settings-reset-requested' }],
+    hostActions: [{ type: 'settings-reset' }],
   };
 }

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

@@ -93,6 +93,9 @@ describe('createRewindCommandModule', () => {
       'restore',
       'code',
       'rollback',
+      'fork',
+      'switch',
+      'branches',
     ]);
     expect(module.systemCommands?.map((command) => command.name)).toEqual(['rewind']);
     expect(module.systemCommands?.[0]?.userInvocable).toBe(true);
@@ -186,6 +189,43 @@ describe('executeRewindCommand', () => {
     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');

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

@@ -7,7 +7,7 @@ import {
 import { executeRewindCommand } from './rewind-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export function createRewindCommandEntry(): ICommand {
   return {
@@ -16,6 +16,7 @@ export function createRewindCommandEntry(): ICommand {
     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(),