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

package/src/mcp-activation/__tests__/mcp-model-view.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createMCPActivationCommandModule } from '../mcp-activation-command-module.js';
+import { executeMCPActivationCommand } from '../mcp-activation-command.js';
+import {
+  mcpUnavailableServersNotice,
+  mcpUserActionCommand,
+  mcpUserActionNotice,
+} from '../mcp-model-notice.js';
+
+import type {
+  ICommandMCPActivationAdapter,
+  ICommandMCPActivationSummary,
+} from '@robota-sdk/agent-framework';
+import type { TCommandInvocationSource } from '@robota-sdk/agent-interface-command';
+
+function summary(overrides: Partial<ICommandMCPActivationSummary>): ICommandMCPActivationSummary {
+  return {
+    serverId: 'server-1',
+    displayName: 'Example server',
+    source: 'project',
+    status: 'pending',
+    allowed: false,
+    reason: 'SECRET-REASON-TEXT from a definition',
+    provenanceId: 'project-settings:/home/me/repo/.robota/settings.json',
+    definitionFingerprint: 'fingerprint-abc',
+    securityIdentity: 'https://user:hunter2@mcp.example.com/?token=abc',
+    ...overrides,
+  };
+}
+
+const adapter: ICommandMCPActivationAdapter = {
+  list: () => [
+    summary({ serverId: 'github', status: 'approved', allowed: true }),
+    summary({ serverId: 'linear', status: 'pending' }),
+    summary({ serverId: 'jira', status: 'untrusted' }),
+    summary({ serverId: 'evil; rm -rf ~', status: 'stale' }),
+    summary({ serverId: 'gone', status: 'rejected' }),
+  ],
+  sourceProblems: () => [
+    { source: 'project', origin: '/home/me/repo/.robota/settings.json', reason: 'not json' },
+  ],
+  approve: () => {
+    throw new Error('not used');
+  },
+  reject: () => {
+    throw new Error('not used');
+  },
+  revoke: () => {
+    throw new Error('not used');
+  },
+  oauthStatus: async () => [{ serverId: 'github', state: 'sign-in-required' }],
+};
+
+function host(source: TCommandInvocationSource) {
+  return createTestCommandHost({
+    overrides: {
+      getCommandHostAdapters: () => ({ mcpActivation: adapter }),
+      getCommandInvocationSource: () => source,
+    },
+  });
+}
+
+describe('/mcp status as the model sees it', () => {
+  it('names each server, its states, and the command to suggest', async () => {
+    const result = await executeMCPActivationCommand(host('model'), 'status');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toBe(
+      [
+        'MCP servers:',
+        '  github — approved — sign-in: sign-in-required — ask the user to run `/mcp login github`',
+        '  linear — pending — ask the user to run `/mcp approve linear`',
+        '  jira — untrusted — ask the user to run `robota trust`',
+        '  (name not shown) — stale — ask the user to run `/mcp approve <server>`',
+        '  gone — rejected',
+        '1 MCP configuration source(s) could not be read; the user can see which with `/mcp status`.',
+      ].join('\n'),
+    );
+  });
+
+  it('names the terminal sign-in command in a run with no session prompt', async () => {
+    const terminal = { ...adapter, userActionSurface: 'terminal' as const };
+    const result = await executeMCPActivationCommand(
+      createTestCommandHost({
+        overrides: {
+          getCommandHostAdapters: () => ({ mcpActivation: terminal }),
+          getCommandInvocationSource: () => 'model',
+        },
+      }),
+      'status',
+    );
+    expect(result.message).toContain(
+      'github — approved — sign-in: sign-in-required — ask the user to run `robota mcp login github`',
+    );
+    expect(result.message).not.toContain('/mcp login');
+    // Approval has no terminal command; it stays the session command.
+    expect(result.message).toContain('`/mcp approve linear`');
+  });
+
+  it('carries no reason text, source path, fingerprint, identity or unsafe name', async () => {
+    const result = await executeMCPActivationCommand(host('model'), '');
+    const everything = JSON.stringify(result);
+
+    for (const leaked of [
+      'SECRET-REASON-TEXT',
+      '/home/me/repo',
+      'fingerprint-abc',
+      'hunter2',
+      'token=abc',
+      'mcp.example.com',
+      'rm -rf',
+      'Example server',
+    ]) {
+      expect(everything).not.toContain(leaked);
+    }
+  });
+
+  it('keeps the full view for the user', async () => {
+    const result = await executeMCPActivationCommand(host('user'), 'status');
+    expect(result.message).toContain('SECRET-REASON-TEXT');
+  });
+
+  it('gives a caller that does not say who it is the restricted view', async () => {
+    const { getCommandInvocationSource: _unsaid, ...anonymous } = host('user');
+    const result = await executeMCPActivationCommand(anonymous, 'status');
+    expect(result.message).toContain('`/mcp approve linear`');
+    expect(result.message).not.toContain('SECRET-REASON-TEXT');
+  });
+});
+
+describe('the `/mcp login` the notices suggest', () => {
+  it('is a real verb for the user and is refused for the model before it runs', async () => {
+    // A user-typed `/mcp login` reaches the sign-in path (here: no host adapter), never "Unknown".
+    const userResult = await executeMCPActivationCommand(
+      createTestCommandHost({ overrides: { getCommandInvocationSource: () => 'user' } }),
+      'login github',
+    );
+    expect(userResult.message).not.toContain('Unknown argument');
+    expect(userResult.message).toContain('not available in this environment');
+
+    const [command] = createMCPActivationCommandModule().systemCommands ?? [];
+    expect(command?.subcommands).toContainEqual(
+      expect.objectContaining({ name: 'login', modelInvocable: false }),
+    );
+    const execute = vi.fn();
+    const executor = new SystemCommandExecutor([{ ...command!, execute }]);
+    const modelResult = await executor.executeModelInvocable(
+      'mcp',
+      createTestCommandHost(),
+      'login github',
+    );
+    expect(modelResult?.success).toBe(false);
+    expect(modelResult?.message).toContain('only the user can');
+    expect(execute).not.toHaveBeenCalled();
+    expect(mcpUserActionCommand('github', 'sign-in')).toBe('/mcp login github');
+  });
+});
+
+describe('MCP notices for the model', () => {
+  it('names a shell-safe server and the user command', () => {
+    expect(mcpUserActionNotice('linear', 'approve')).toBe(
+      'MCP server "linear" is waiting for the user’s approval, so its tools are unavailable. You ' +
+        'cannot do this yourself; ask the user to run `/mcp approve linear`.',
+    );
+    expect(mcpUserActionNotice('github', 'sign-in')).toContain('`/mcp login github`');
+    expect(mcpUserActionNotice('jira', 'trust-workspace')).toContain(
+      '`robota trust` in a terminal, then restart the session',
+    );
+  });
+
+  it('names the terminal sign-in command where no /mcp command can be typed', () => {
+    expect(mcpUserActionNotice('github', 'sign-in', 'terminal')).toBe(
+      'MCP server "github" needs the user to sign in, so its tools are unavailable. You cannot do ' +
+        'this yourself; ask the user to run `robota mcp login github` in a terminal, then restart ' +
+        'the session.',
+    );
+    expect(mcpUserActionCommand('$(curl evil)', 'sign-in', 'terminal')).toBe(
+      'robota mcp login <server>',
+    );
+    // Only sign-in moves: approval has no terminal command.
+    expect(mcpUserActionCommand('linear', 'approve', 'terminal')).toBe('/mcp approve linear');
+  });
+
+  it('stays generic for a name that is not safe to show', () => {
+    const notice = mcpUserActionNotice('$(curl evil)', 'sign-in');
+    expect(notice).not.toContain('curl');
+    expect(notice).toContain('`/mcp status` lists it');
+    expect(mcpUserActionCommand('$(curl evil)', 'approve')).toBe('/mcp approve <server>');
+  });
+
+  it('lists every unavailable server, or says nothing', () => {
+    expect(mcpUnavailableServersNotice(new Map())).toBeUndefined();
+    const notice = mcpUnavailableServersNotice(
+      new Map([
+        ['linear', 'approve'],
+        ['github', 'sign-in'],
+      ]),
+    );
+    expect(notice?.split('\n')).toEqual([
+      'MCP servers that did not start this session. Mention this only when the user needs one of ' +
+        'these servers or its tools:',
+      `- ${mcpUserActionNotice('linear', 'approve')}`,
+      `- ${mcpUserActionNotice('github', 'sign-in')}`,
+    ]);
+  });
+});

package/src/mcp-activation/index.ts

@@ -0,0 +1,12 @@
+export {
+  createMCPActivationCommandEntry,
+  createMCPActivationCommandModule,
+  MCPActivationCommandSource,
+} from './mcp-activation-command-module.js';
+export { executeMCPActivationCommand } from './mcp-activation-command.js';
+export {
+  mcpUnavailableServersNotice,
+  mcpUserActionCommand,
+  mcpUserActionNotice,
+} from './mcp-model-notice.js';
+export type { TMCPUserAction, TMCPUserActionSurface } from './mcp-model-notice.js';

package/src/mcp-activation/mcp-activation-command-module.ts

@@ -0,0 +1,92 @@
+import { executeMCPActivationCommand } from './mcp-activation-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createMCPActivationCommandEntry(): ICommand {
+  return {
+    name: 'mcp',
+    displayName: 'MCP activation',
+    description:
+      "Show each MCP server's trust approval and OAuth sign-in state, or change one server: " +
+      'approve, reject or revoke its trust; sign in to it (login, which connects it in this ' +
+      'session) or out of it (logout). Use when an MCP server is not approved, needs a sign-in, or ' +
+      'should stop being used. Returns the status list, or what the one action did.',
+    // Model-invocable for `status` only: when an MCP server's tools are missing or failing, the
+    // model can see why and name the command the user should run. Approving, rejecting and revoking
+    // a server are trust decisions and signing in or out is a credential action, so those stay
+    // user-only — the model's `status` view also omits everything but names and states.
+    modelDescription:
+      'Show which MCP servers are configured and why any of them is unavailable. Use it when an MCP ' +
+      'server or its tools are missing, a tool call reports that a server needs sign-in or approval, ' +
+      'or the user asks about MCP servers. Returns one line per server: its name, activation state, ' +
+      'sign-in state, and the command to suggest to the user when the server needs their approval, ' +
+      'sign-in or workspace trust. You cannot approve, sign in or sign out yourself.',
+    argumentHint:
+      '[status] | <approve|reject|revoke|logout> <server> | login <server> [--no-browser]',
+    source: 'mcp-activation',
+    modelInvocable: true,
+    // The bare `/mcp` shows the status view, so choosing it from a menu runs it.
+    runsBare: true,
+    subcommands: [
+      {
+        name: 'status',
+        description: 'Show every MCP server’s name, activation state and sign-in state',
+        source: 'mcp-activation',
+        modelInvocable: true,
+      },
+      ...(['approve', 'reject', 'revoke', 'login', 'logout'] as const).map((verb) => ({
+        name: verb,
+        description: USER_ONLY_VERB_DESCRIPTION[verb],
+        argumentHint: verb === 'login' ? '<server> [--no-browser]' : '<server>',
+        source: 'mcp-activation',
+        modelInvocable: false,
+      })),
+    ],
+  };
+}
+
+const USER_ONLY_VERB_DESCRIPTION = {
+  approve: 'Trust and activate an MCP server',
+  reject: 'Refuse an MCP server',
+  revoke: 'Withdraw an earlier approval',
+  login: 'Sign in to an OAuth MCP server and connect it in this session',
+  logout: 'Sign out of an OAuth MCP server and revoke its tokens',
+} as const;
+
+function createMCPActivationSystemCommand(): ISystemCommand {
+  const entry = createMCPActivationCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    ...(entry.modelDescription !== undefined ? { modelDescription: entry.modelDescription } : {}),
+    argumentHint: entry.argumentHint,
+    ...(entry.subcommands !== undefined ? { subcommands: entry.subcommands } : {}),
+    // Approve/reject/revoke/login/logout change trust or credentials, so the command is never read-only
+    // for the user or a remote policy. The model can reach only `status` (its subcommand
+    // allowlist), a read-only view, so its call needs no prompt.
+    requiresPermission: true,
+    modelRequiresPermission: false,
+    userInvocable: true,
+    modelInvocable: true,
+    lifecycle: 'inline',
+    execute: executeMCPActivationCommand,
+  };
+}
+
+export class MCPActivationCommandSource implements ICommandSource {
+  readonly name = 'mcp-activation';
+
+  getCommands(): ICommand[] {
+    return [createMCPActivationCommandEntry()];
+  }
+}
+
+export function createMCPActivationCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-mcp-activation',
+    commandSources: [new MCPActivationCommandSource()],
+    systemCommands: [createMCPActivationSystemCommand()],
+  };
+}