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

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

@@ -0,0 +1,242 @@
+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/.fixture-state/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/.fixture-state/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, cliName = 'test-agent', terminal = false) {
+  return createTestCommandHost({
+    overrides: {
+      getCommandHostAdapters: () => ({
+        mcpActivation: terminal ? { ...adapter, userActionSurface: 'terminal' } : adapter,
+      }),
+      getCommandInvocationSource: () => source,
+      getCommandProductVocabulary: () => ({ cliName, displayName: cliName }),
+    },
+  });
+}
+
+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 `test-agent 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',
+          getCommandProductVocabulary: () => ({ cliName: 'test-agent', displayName: 'Test Agent' }),
+        },
+      }),
+      'status',
+    );
+    expect(result.message).toContain(
+      'github — approved — sign-in: sign-in-required — ask the user to run `test-agent 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', 'session', 'test-agent')).toContain(
+      '`test-agent 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', 'test-agent')).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 `test-agent mcp login github` in a terminal, then restart ' +
+        'the session.',
+    );
+    expect(mcpUserActionCommand('$(curl evil)', 'sign-in', 'terminal', 'test-agent')).toBe(
+      'test-agent mcp login <server>',
+    );
+    // Only sign-in moves: approval has no terminal command.
+    expect(mcpUserActionCommand('linear', 'approve', 'terminal')).toBe('/mcp approve linear');
+  });
+
+  it('uses the command vocabulary supplied by each host and stays generic when it is absent', async () => {
+    const first = await executeMCPActivationCommand(host('model', 'alpha-agent', true), 'status');
+    const second = await executeMCPActivationCommand(host('model', 'beta-agent', true), 'status');
+    const noVocabulary = createTestCommandHost({
+      overrides: {
+        getCommandHostAdapters: () => ({
+          mcpActivation: { ...adapter, userActionSurface: 'terminal' },
+        }),
+        getCommandInvocationSource: () => 'model',
+      },
+    });
+    const generic = await executeMCPActivationCommand(noVocabulary, 'status');
+
+    expect(first.message).toContain('`alpha-agent mcp login github`');
+    expect(first.message).not.toContain('beta-agent');
+    expect(second.message).toContain('`beta-agent mcp login github`');
+    expect(second.message).not.toContain('alpha-agent');
+    expect(generic.message).not.toContain('mcp login');
+    expect(generic.message).not.toMatch(/undefined|fixture-agent/i);
+    expect(mcpUserActionNotice('jira', 'trust-workspace', 'session', 'alpha-agent')).toContain(
+      '`alpha-agent trust` in a terminal, then restart the session',
+    );
+    expect(mcpUserActionNotice('jira', 'trust-workspace')).toContain(
+      'ask the user to trust this workspace in a terminal',
+    );
+  });
+
+  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/__tests__/mcp-skill-command.test.ts

@@ -0,0 +1,141 @@
+import { expect, it, vi } from 'vitest';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+import { executeMCPActivationCommand } from '../mcp-activation-command.js';
+import { createMCPActivationCommandModule } from '../mcp-activation-command-module.js';
+import type { TCommandInvocationSource } from '@robota-sdk/agent-interface-command';
+
+const preview = {
+  serverId: 'docs',
+  uri: 'skill://docs/demo/SKILL.md',
+  namespace: 'origin',
+  fingerprint: 'a'.repeat(64),
+  name: 'demo',
+  description: 'Use this workflow',
+  frontmatter: { name: 'demo', description: 'Use this workflow', 'allowed-tools': 'Write' },
+  content: '---\nname: demo\n---\nInstructions for review.',
+};
+function fixture(source: TCommandInvocationSource | undefined, locality?: 'local' | 'remote') {
+  const skills = {
+    list: vi.fn(async () => [{ ...preview, content: undefined }]),
+    inspect: vi.fn(async () => preview),
+    approve: vi.fn(async () => preview),
+    withdraw: vi.fn(),
+  };
+  const host = createTestCommandHost({
+    overrides: {
+      getCommandHostAdapters: () => ({
+        mcpActivation: {
+          list: () => [],
+          approve: vi.fn(),
+          reject: vi.fn(),
+          revoke: vi.fn(),
+          skills,
+        },
+      }),
+      getCommandInvocationSource: () => source ?? 'user',
+      getCommandSurfaceLocalityEvidence: () => locality,
+    },
+  });
+  const {
+    getCommandInvocationSource: _source,
+    getCommandSurfaceLocalityEvidence: _locality,
+    ...base
+  } = host;
+  return {
+    skills,
+    host: {
+      ...base,
+      ...(source === undefined ? {} : { getCommandInvocationSource: () => source }),
+      ...(locality === undefined ? {} : { getCommandSurfaceLocalityEvidence: () => locality }),
+    },
+  };
+}
+
+it('lists model-visible metadata without inspecting or approving instructions', async () => {
+  const f = fixture('model');
+  const result = await executeMCPActivationCommand(f.host, 'skill-list docs');
+  expect(result.success).toBe(true);
+  expect(result.message).toContain('Use this workflow');
+  expect(f.skills.list).toHaveBeenCalledWith('docs');
+  expect(f.skills.inspect).not.toHaveBeenCalled();
+  expect(f.skills.approve).not.toHaveBeenCalled();
+});
+
+it('shows exact content and supplies a content-bound approval command for the user', async () => {
+  const f = fixture('user');
+  const result = await executeMCPActivationCommand(
+    f.host,
+    'skill-inspect docs skill://docs/demo/SKILL.md',
+  );
+  expect(result.success).toBe(true);
+  expect(result.message).toContain(preview.content);
+  expect(result.message).toContain(
+    `/mcp skill-approve docs skill://docs/demo/SKILL.md ${preview.fingerprint}`,
+  );
+  expect(f.skills.approve).not.toHaveBeenCalled();
+});
+
+it.each(['model', 'remote', undefined] as const)(
+  'refuses consent actions from %s before dispatch',
+  async (source) => {
+    const f = fixture(source);
+    for (const verb of ['skill-inspect', 'skill-approve', 'skill-withdraw']) {
+      const result = await executeMCPActivationCommand(
+        f.host,
+        `${verb} docs skill://docs/demo/SKILL.md ${preview.fingerprint}`,
+      );
+      expect(result.success).toBe(false);
+      expect(result.message).toContain('local user');
+    }
+    expect(f.skills.inspect).not.toHaveBeenCalled();
+    expect(f.skills.approve).not.toHaveBeenCalled();
+    expect(f.skills.withdraw).not.toHaveBeenCalled();
+  },
+);
+
+it('allows a proven local app user and refuses another-device transport', async () => {
+  const f = fixture('remote', 'local');
+  expect(
+    (
+      await executeMCPActivationCommand(
+        f.host,
+        `skill-approve docs ${preview.uri} ${preview.fingerprint}`,
+      )
+    ).success,
+  ).toBe(true);
+  expect(f.skills.approve).toHaveBeenCalledWith('docs', preview.uri, preview.fingerprint, 'user');
+  const remote = fixture('remote', 'remote');
+  expect(
+    (
+      await executeMCPActivationCommand(
+        remote.host,
+        `skill-approve docs ${preview.uri} ${preview.fingerprint}`,
+      )
+    ).success,
+  ).toBe(false);
+  expect(remote.skills.approve).not.toHaveBeenCalled();
+});
+
+it('allows only metadata listing through the model command executor', async () => {
+  const [command] = createMCPActivationCommandModule().systemCommands ?? [];
+  const execute = vi.fn();
+  const executor = new SystemCommandExecutor([{ ...command!, execute }]);
+  for (const verb of ['skill-inspect', 'skill-approve', 'skill-withdraw'])
+    expect(
+      (await executor.executeModelInvocable('mcp', createTestCommandHost(), `${verb} docs`))
+        ?.success,
+    ).toBe(false);
+  expect(execute).not.toHaveBeenCalled();
+  await executor.executeModelInvocable('mcp', createTestCommandHost(), 'skill-list docs');
+  expect(execute).toHaveBeenCalledOnce();
+});
+
+it('accepts JSON argument arrays for opaque names and URIs without shell evaluation', async () => {
+  const f = fixture('user');
+  const args = ['docs with spaces', 'skill://host/demo/SKILL.md?label=a b'];
+  expect(
+    (await executeMCPActivationCommand(f.host, `skill-inspect ${JSON.stringify(args)}`)).success,
+  ).toBe(true);
+  expect(f.skills.inspect).toHaveBeenCalledWith(...args);
+});

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,123 @@
+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. List MCP Skills metadata, inspect exact instructions, approve their ' +
+      'content fingerprint or withdraw content consent separately from server trust. Returns the status list, verified preview, or what the 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. Use skill-list <server> to discover advertised skill names, URIs ' +
+      'and descriptions without loading instructions. Returns an invocation name for each supported ' +
+      'skill; use the session skill activation command with that exact name when its workflow fits ' +
+      'the task. If content consent is needed, ask the user to ' +
+      'run /mcp skill-inspect <server> <uri> and approve the reviewed fingerprint. You cannot approve, inspect instructions, 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,
+      },
+      {
+        name: 'skill-list',
+        description:
+          'Discover MCP skill metadata and exact invocation names, or reasons they are unavailable, without activating instructions',
+        argumentHint: '<server>',
+        source: 'mcp-activation',
+        modelInvocable: true,
+      },
+      ...(['skill-inspect', 'skill-approve', 'skill-withdraw'] as const).map((verb) => ({
+        name: verb,
+        description:
+          verb === 'skill-inspect'
+            ? 'Review verified MCP skill instructions and frontmatter without activation'
+            : verb === 'skill-approve'
+              ? 'Grant consent for an exactly reviewed MCP skill content fingerprint'
+              : 'Withdraw MCP skill content consent',
+        argumentHint: verb === 'skill-approve' ? '<server> <uri> <fingerprint>' : '<server> <uri>',
+        source: 'mcp-activation',
+        modelInvocable: false,
+      })),
+      {
+        name: 'reload',
+        description: 'Retry connecting every MCP server that is not currently connected',
+        source: 'mcp-activation',
+        modelInvocable: false,
+      },
+      ...(['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()],
+  };
+}