Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat: the chat composer offers the room's commands on a starting !

raullopez-sandbox0f408ab53268
diff --git a/console/apps/switch-console-desktop/src/main/core/chats/controller.ts b/console/apps/switch-console-desktop/src/main/core/chats/controller.ts
index a2f887528..71c1ac74a 100644
--- a/console/apps/switch-console-desktop/src/main/core/chats/controller.ts
+++ b/console/apps/switch-console-desktop/src/main/core/chats/controller.ts
@@ -16,6 +16,7 @@ import type {
RoomActivity,
} from '@shared/core/chats/activity';
import type {
+ ChatCommand,
ChatMember,
ChatMessage,
ChatMessagesPage,
@@ -44,6 +45,7 @@ import {
fetchChatMessages,
fetchRoomActivity,
fetchThreadMessages,
+ listChatCommands,
listChatMembers,
listChats,
listWorkspaceMembers,
@@ -181,6 +183,9 @@ export const chatsController = createRPCController({
onServer(params.serverId, (server) => removeChatAgent(server, params.roomId, params.agentId)),
members: (serverId: string, roomId: string): Promise<ChatMember[]> =>
onServer(serverId, (server) => listChatMembers(server, roomId)),
+ /** The room commands a member can type here, for the composer's `!` list. */
+ commands: (serverId: string, roomId: string): Promise<ChatCommand[]> =>
+ onServer(serverId, (server) => listChatCommands(server, roomId)),
addMember: (params: {
serverId: string;
roomId: string;
diff --git a/console/apps/switch-console-desktop/src/main/core/chats/gateway.ts b/console/apps/switch-console-desktop/src/main/core/chats/gateway.ts
index ff2fd3eb4..6abd29687 100644
--- a/console/apps/switch-console-desktop/src/main/core/chats/gateway.ts
+++ b/console/apps/switch-console-desktop/src/main/core/chats/gateway.ts
@@ -26,7 +26,9 @@ import {
type ChatUpload,
chatUploadSchema,
chatAgentAddedSchema,
+ type ChatCommand,
type ChatMember,
+ chatCommandListSchema,
chatMemberListSchema,
type WorkspaceMember,
workspaceMemberSchema,
@@ -175,6 +177,14 @@ export async function listChatMembers(server: SwitchServer, roomId: string): Pro
return (await json(server, `${room(roomId)}/members`, chatMemberListSchema)).members;
}
+/** The room commands a member can type in this room (`GET /chats/{room}/commands`). */
+export async function listChatCommands(
+ server: SwitchServer,
+ roomId: string
+): Promise<ChatCommand[]> {
+ return (await json(server, `${room(roomId)}/commands`, chatCommandListSchema)).commands;
+}
+
export async function addChatMember(
server: SwitchServer,
roomId: string,
diff --git a/console/apps/switch-console-desktop/src/renderer/features/chats/command-query.test.ts b/console/apps/switch-console-desktop/src/renderer/features/chats/command-query.test.ts
new file mode 100644
index 000000000..18256c209
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/chats/command-query.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { commandQuery, filterCommands } from './command-query';
+
+const command = (name: string) => ({ name, description: name, usage: `!${name}` });
+
+describe('commandQuery', () => {
+ it('reads a command only at the start of the message, while its name is being typed', () => {
+ expect(commandQuery('!', 1)).toEqual({ start: 0, query: '' });
+ expect(commandQuery('!res', 4)).toEqual({ start: 0, query: 'res' });
+ expect(commandQuery('!reset @helper', 14)).toBeNull();
+ expect(commandQuery('hello !reset', 12)).toBeNull();
+ expect(commandQuery('!reset', 0)).toBeNull();
+ });
+});
+
+describe('filterCommands', () => {
+ it('lists the commands a name starts first, then those containing it', () => {
+ const commands = [command('help'), command('reset-all-agents'), command('reset')];
+ expect(filterCommands(commands, 're').map((each) => each.name)).toEqual([
+ 'reset-all-agents',
+ 'reset',
+ ]);
+ expect(filterCommands(commands, 'all').map((each) => each.name)).toEqual(['reset-all-agents']);
+ expect(filterCommands(commands, '')).toHaveLength(3);
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/renderer/features/chats/command-query.ts b/console/apps/switch-console-desktop/src/renderer/features/chats/command-query.ts
new file mode 100644
index 000000000..5dadf8808
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/chats/command-query.ts
@@ -0,0 +1,21 @@
+import type { ChatCommand } from '@shared/core/chats/chats';
+
+/**
+ * The room command being typed: a `!` that starts the message, and the name so
+ * far, while the caret is still in it. A `!` anywhere else is just text.
+ */
+export function commandQuery(text: string, caret: number): { start: 0; query: string } | null {
+ if (!text.startsWith('!') || caret < 1) return null;
+ const typed = text.slice(1, caret);
+ return /\s/.test(typed) ? null : { start: 0, query: typed };
+}
+
+/** The commands matching what was typed: those it starts first, then those containing it. */
+export function filterCommands(commands: readonly ChatCommand[], query: string): ChatCommand[] {
+ const typed = query.toLowerCase();
+ const starting = commands.filter((command) => command.name.toLowerCase().startsWith(typed));
+ const containing = commands.filter(
+ (command) => !starting.includes(command) && command.name.toLowerCase().includes(typed)
+ );
+ return [...starting, ...containing];
+}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/chats/components/chat-composer.tsx b/console/apps/switch-console-desktop/src/renderer/features/chats/components/chat-composer.tsx
index f7b7ebf4c..15fb8c14a 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/chats/components/chat-composer.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/chats/components/chat-composer.tsx
@@ -1,3 +1,4 @@
+import { useQuery } from '@tanstack/react-query';
import { ChevronDown, Minimize2, Plus, RotateCcw, RotateCw, X } from 'lucide-react';
import { observer } from 'mobx-react-lite';
import { type KeyboardEvent as ReactKeyboardEvent, useEffect, useRef, useState } from 'react';
@@ -7,6 +8,7 @@ import { workspacesStore } from '@renderer/features/workspaces/workspaces-store'
import { AgentAvatar } from '@renderer/lib/components/agent-avatar';
import { isEditableTarget } from '@renderer/lib/hooks/use-arrow-key-navigation';
import { useFeatureFlags } from '@renderer/lib/hooks/useFeatureFlags';
+import { rpc } from '@renderer/lib/ipc';
import { modalStore } from '@renderer/lib/modal/modal-store';
import { Button } from '@renderer/lib/ui/button';
import { Popover, PopoverContent, PopoverTitle, PopoverTrigger } from '@renderer/lib/ui/popover';
@@ -14,11 +16,13 @@ import { cn } from '@renderer/utils/utils';
import { agentInitials } from '@shared/core/agents/agent-avatar';
import {
type ChatAgent,
+ type ChatCommand,
type ChatMessage,
chatAgentLabel,
requestIdOfClientTxn,
} from '@shared/core/chats/chats';
import { snippetOf } from '../chat-threads';
+import { commandQuery, filterCommands } from '../command-query';
import {
agentTargets,
composeMentions,
@@ -64,7 +68,8 @@ function chatFile(file: File): ChatFile {
type Suggestion =
| { kind: 'agent'; id: string; agent: ChatAgent }
- | { kind: 'person'; id: string; person: MentionPerson & { email: string | null } };
+ | { kind: 'person'; id: string; person: MentionPerson & { email: string | null } }
+ | { kind: 'command'; id: string; command: ChatCommand };
/** Chats just created here, whose composer takes focus when it first shows. */
const focusOnOpen = new Set<string>();
@@ -318,21 +323,30 @@ export const ChatComposer = observer(function ChatComposer({
const agentNamed = tokens.some((token) => token.kind === 'agent');
const mentionable =
(agents.length > 0 && (groupChats || !agentNamed)) || mentionPeople.length > 0;
- const query = mentionable ? mentionQuery(draft, caret) : null;
- const suggestions: Suggestion[] = query
- ? [
- ...filterMentionAgents(agents, query.query).map((agent): Suggestion => ({
- kind: 'agent',
- id: agent.id,
- agent,
- })),
- ...filterMentionPeople(mentionPeople, query.query).map((person): Suggestion => ({
- kind: 'person',
- id: `user:${person.userId}`,
- person,
- })),
- ]
- : [];
+ // A `!` that starts the message offers the room's commands, as the server lists them.
+ const typingCommand = commandQuery(draft, caret);
+ const commands = useQuery({
+ queryKey: ['chat-commands', serverId, timeline.roomId],
+ queryFn: () => rpc.chats.commands(serverId, timeline.roomId),
+ enabled: typingCommand !== null,
+ staleTime: 5 * 60_000,
+ retry: false,
+ });
+ const query = typingCommand ?? (mentionable ? mentionQuery(draft, caret) : null);
+ const suggestions: Suggestion[] = typingCommand
+ ? filterCommands(commands.data ?? [], typingCommand.query).map(
+ (command): Suggestion => ({ kind: 'command', id: `command:${command.name}`, command })
+ )
+ : query
+ ? [
+ ...filterMentionAgents(agents, query.query).map(
+ (agent): Suggestion => ({ kind: 'agent', id: agent.id, agent })
+ ),
+ ...filterMentionPeople(mentionPeople, query.query).map(
+ (person): Suggestion => ({ kind: 'person', id: `user:${person.userId}`, person })
+ ),
+ ]
+ : [];
const suggesting = query !== null && query.start !== dismissedAt && suggestions.length > 0;
const activeIndex = Math.min(mentionIndex, suggestions.length - 1);
const listId = `mentions-${timeline.roomId}`;
@@ -377,6 +391,17 @@ export const ChatComposer = observer(function ChatComposer({
const pick = (choice: Suggestion) => {
const textarea = input.current;
if (!textarea || !query) return;
+ if (choice.kind === 'command') {
+ const typed = `!${choice.command.name} `;
+ textarea.focus();
+ textarea.setSelectionRange(0, caret);
+ if (!document.execCommand('insertText', false, typed)) {
+ edit(`${typed}${draft.slice(caret)}`, null);
+ setCaret(typed.length);
+ }
+ setMentionIndex(0);
+ return;
+ }
const name = choice.kind === 'agent' ? choice.agent.name : choice.person.name;
pendingPick.current = {
kind: choice.kind,
@@ -544,7 +569,7 @@ export const ChatComposer = observer(function ChatComposer({
<div
id={listId}
role="listbox"
- aria-label="Mention an agent or person"
+ aria-label={typingCommand ? 'Room commands' : 'Mention an agent or person'}
className="absolute bottom-full left-0 z-50 mb-3 flex max-h-60 w-72 flex-col overflow-y-auto rounded-md border bg-background-quaternary p-1 text-sm shadow-sm"
>
{suggestions.map((each, index) => (
@@ -562,7 +587,14 @@ export const ChatComposer = observer(function ChatComposer({
onMouseDown={(event) => event.preventDefault()}
onClick={() => pick(each)}
>
- {each.kind === 'agent' ? (
+ {each.kind === 'command' ? (
+ <span className="flex min-w-0 flex-col">
+ <span className="truncate font-medium">{each.command.usage}</span>
+ <span className="truncate text-xs text-foreground-muted">
+ {each.command.description}
+ </span>
+ </span>
+ ) : each.kind === 'agent' ? (
<>
<AgentAvatar
name={each.agent.name}
@@ -632,9 +664,9 @@ export const ChatComposer = observer(function ChatComposer({
placeholder={disabled ?? `Message ${recipient}...`}
value={draft}
disabled={disabled !== null}
- role={mentionable ? 'combobox' : undefined}
- aria-autocomplete={mentionable ? 'list' : undefined}
- aria-expanded={mentionable ? suggesting : undefined}
+ role="combobox"
+ aria-autocomplete="list"
+ aria-expanded={suggesting}
aria-controls={suggesting ? listId : undefined}
aria-activedescendant={
suggesting ? `${listId}-${suggestions[activeIndex]!.id}` : undefined
@@ -644,7 +676,10 @@ export const ChatComposer = observer(function ChatComposer({
edit(event.target.value, (event.nativeEvent as InputEvent).inputType ?? null);
setCaret(event.target.selectionStart);
setMentionIndex(0);
- if (!mentionQuery(event.target.value, event.target.selectionStart))
+ if (
+ !mentionQuery(event.target.value, event.target.selectionStart) &&
+ !commandQuery(event.target.value, event.target.selectionStart)
+ )
setDismissedAt(null);
}}
onSelect={(event) => setCaret(event.currentTarget.selectionStart)}
diff --git a/console/apps/switch-console-desktop/src/renderer/tests/browser/chat-composer-commands.test.tsx b/console/apps/switch-console-desktop/src/renderer/tests/browser/chat-composer-commands.test.tsx
new file mode 100644
index 000000000..5b703b00a
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/tests/browser/chat-composer-commands.test.tsx
@@ -0,0 +1,120 @@
+/**
+ * A `!` that starts a message offers the room's commands, from the server's
+ * list: typed on, they narrow; arrows move, Enter or Tab inserts `!name `, Esc
+ * closes. A `!` later in the message is just text.
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, expect, it, vi } from 'vitest';
+
+const commands = vi.hoisted(() =>
+ vi.fn(async () => [
+ { name: 'help', description: 'Show this list of commands.', usage: '!help' },
+ { name: 'reset', description: "Reset a targeted agent's session.", usage: '!reset <target>' },
+ { name: 'reset-all-agents', description: 'Reset every agent.', usage: '!reset-all-agents' },
+ ])
+);
+vi.mock('@renderer/lib/ipc', () => ({
+ events: { on: () => () => {} },
+ rpc: { chats: { commands } },
+}));
+vi.mock('@renderer/lib/hooks/useFeatureFlags', () => ({
+ useFeatureFlags: () => ({ group_chats: true }),
+}));
+
+import { ChatComposer } from '@renderer/features/chats/components/chat-composer';
+import {
+ ChatTimeline,
+ type TimelineApi,
+} from '@renderer/features/chats/stores/chat-timeline-store';
+
+let container: HTMLDivElement | null = null;
+let root: Root | null = null;
+
+afterEach(async () => {
+ if (root) await act(async () => root!.unmount());
+ container?.remove();
+ container = null;
+ root = null;
+});
+
+async function render(): Promise<HTMLTextAreaElement> {
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ root = createRoot(container);
+ await act(async () =>
+ root!.render(
+ <QueryClientProvider client={new QueryClient()}>
+ <ChatComposer
+ serverId="s"
+ timeline={new ChatTimeline('room-commands', {} as TimelineApi)}
+ agents={[]}
+ people={[]}
+ groupName="Ship review"
+ activity={null}
+ replyTo={null}
+ onClearReply={() => {}}
+ disabled={null}
+ />
+ </QueryClientProvider>
+ )
+ );
+ return container.querySelector('textarea')!;
+}
+
+async function type(textarea: HTMLTextAreaElement, value: string): Promise<void> {
+ await act(async () => {
+ textarea.focus();
+ textarea.select();
+ document.execCommand('insertText', false, value);
+ });
+ for (let i = 0; i < 3; i++) await act(async () => await Promise.resolve());
+}
+
+const key = (textarea: HTMLTextAreaElement, name: string) =>
+ act(async () => {
+ textarea.dispatchEvent(
+ new KeyboardEvent('keydown', { key: name, bubbles: true, cancelable: true })
+ );
+ });
+
+const options = () =>
+ [...container!.querySelectorAll('[role="option"]')].map(
+ (option) => option.querySelector('.font-medium')?.textContent
+ );
+
+it('offers the room’s commands on a starting !, narrowing as the name is typed', async () => {
+ const textarea = await render();
+ await type(textarea, '!');
+ expect(container!.querySelector('[role="listbox"]')?.getAttribute('aria-label')).toBe(
+ 'Room commands'
+ );
+ expect(options()).toEqual(['!help', '!reset <target>', '!reset-all-agents']);
+ await type(textarea, '!res');
+ expect(options()).toEqual(['!reset <target>', '!reset-all-agents']);
+ expect(commands).toHaveBeenCalledWith('s', 'room-commands');
+});
+
+it('inserts the picked command with a space after it, by arrows and Enter or Tab', async () => {
+ const textarea = await render();
+ await type(textarea, '!res');
+ await key(textarea, 'ArrowDown');
+ await key(textarea, 'ArrowUp');
+ await key(textarea, 'Enter');
+ expect(textarea.value).toBe('!reset ');
+ expect(container!.querySelector('[role="listbox"]')).toBeNull();
+
+ await type(textarea, '!he');
+ await key(textarea, 'Tab');
+ expect(textarea.value).toBe('!help ');
+});
+
+it('closes on Esc, and offers nothing for a ! later in the message', async () => {
+ const textarea = await render();
+ await type(textarea, '!');
+ await key(textarea, 'Escape');
+ expect(container!.querySelector('[role="listbox"]')).toBeNull();
+ await type(textarea, 'hello !res');
+ expect(container!.querySelector('[role="listbox"]')).toBeNull();
+});
diff --git a/console/apps/switch-console-desktop/src/shared/core/chats/chats.ts b/console/apps/switch-console-desktop/src/shared/core/chats/chats.ts
index 1fba5bf88..012f6172f 100644
--- a/console/apps/switch-console-desktop/src/shared/core/chats/chats.ts
+++ b/console/apps/switch-console-desktop/src/shared/core/chats/chats.ts
@@ -117,6 +117,16 @@ export const chatMemberSchema = z.object({
});
export type ChatMember = z.infer<typeof chatMemberSchema>;
export const chatMemberListSchema = z.object({ members: z.array(chatMemberSchema) });
+
+/** A room command a member can type (`!name`), as the server's command list has it. */
+export const chatCommandSchema = z.object({
+ name: z.string(),
+ description: z.string(),
+ /** How it is typed, with its arguments: `!reset <target>`. */
+ usage: z.string(),
+});
+export type ChatCommand = z.infer<typeof chatCommandSchema>;
+export const chatCommandListSchema = z.object({ commands: z.array(chatCommandSchema) });
/** A person in the workspace, from its roster, who could be added to a chat. */
export const workspaceMemberSchema = z
.object({
diff --git a/console/tooling-e2e/surface/exemptions.json b/console/tooling-e2e/surface/exemptions.json
index 53eec2ab9..2c50c93cc 100644
--- a/console/tooling-e2e/surface/exemptions.json
+++ b/console/tooling-e2e/surface/exemptions.json
@@ -5,6 +5,7 @@
"GET /gateway/auth/oidc/callback": "Needs a live OIDC identity provider; the harness signs in with a password.",
"GET /gateway/auth/oidc/login": "Needs a live OIDC identity provider; the harness signs in with a password.",
"GET /gateway/chats/agent-candidates": "Switch Console group chats. Covered by core's test_chats_groups.py against real Postgres; no scenario drives Console chats yet (every other /gateway/chats route is still in the backlog), and the stacks the harness builds do not turn on the group_chats flag these routes need.",
+ "GET /gateway/chats/{room_id}/commands": "The commands the chat composer offers on `!`. Covered by core's test_chats_controls.py against real Postgres; no scenario drives Console chats yet, and the stacks the harness builds do not turn on the group_chats flag.",
"GET /gateway/chats/{room_id}/threads/{root_id}/messages": "Switch Console group chats. Covered by core's test_chats_groups.py against real Postgres; no scenario drives Console chats yet (every other /gateway/chats route is still in the backlog), and the stacks the harness builds do not turn on the group_chats flag these routes need.",
"GET /gateway/docs": "FastAPI's generated API documentation; no behaviour of Switch's own to cover.",
"GET /gateway/docs/oauth2-redirect": "FastAPI's generated API documentation; no behaviour of Switch's own to cover.",
diff --git a/console/tooling-e2e/surface/server-surface.json b/console/tooling-e2e/surface/server-surface.json
index 0baec35a0..075824ad0 100644
--- a/console/tooling-e2e/surface/server-surface.json
+++ b/console/tooling-e2e/surface/server-surface.json
@@ -377,6 +377,11 @@
"auth": "session",
"flags": []
},
+ {
+ "route": "GET /gateway/chats/{room_id}/commands",
+ "auth": "session",
+ "flags": []
+ },
{
"route": "GET /gateway/chats/{room_id}/media",
"auth": "session",
diff --git a/core/switch_core/gateway/chats.py b/core/switch_core/gateway/chats.py
index 7557b9a78..e10f7d4f5 100644
--- a/core/switch_core/gateway/chats.py
+++ b/core/switch_core/gateway/chats.py
@@ -34,6 +34,7 @@ from fastapi import (
from fastapi.responses import JSONResponse, StreamingResponse
from sqlalchemy.ext.asyncio import AsyncSession
+from switch_core.bridges.agent.commands import COMMANDS
from switch_core.chats.service import (
ChatError,
ChatService,
@@ -173,6 +174,17 @@ class MemberList(CamelModel):
members: list[ChatMember]
+class ChatCommand(CamelModel):
+ name: str
+ description: str
+ # How it is typed, with its arguments: `!reset <target>`.
+ usage: str
+
+
+class ChatCommands(CamelModel):
+ commands: list[ChatCommand]
+
+
class AddMemberRequest(CamelModel):
user_id: str
@@ -511,6 +523,35 @@ async def list_members(room_id: str, user: CurrentUser, service: Service) -> Mem
return await _member_list(service, session, room)
[email protected]("/{room_id}/commands", response_model=ChatCommands)
+async def list_commands(
+ room_id: str, user: CurrentUser, service: Service
+) -> ChatCommands:
+ """The room commands a member can type here (`!name`), as the platforms'
+ command lists show them: those that do something and are not hidden."""
+ tenant_id = require_tenant_id()
+ async with tenant_session(service.session_factory, tenant_id) as session:
+ await service.require_member(session, tenant_id, user, room_id)
+ return ChatCommands(
+ commands=[
+ ChatCommand(
+ name=command.name,
+ description=command.description,
+ usage=" ".join(
+ [
+ f"!{command.name}",
+ *(f"<{arg.name}>" for arg in command.args_spec),
+ ]
+ ),
+ )
+ for command in COMMANDS
+ if command.handler is not None
+ and not command.hidden
+ and command.description.strip()
+ ]
+ )
+
+
@router.post("/{room_id}/members", response_model=MemberList)
async def add_member(
room_id: str, req: AddMemberRequest, user: CurrentUser, service: Service
diff --git a/core/tests/switch_core/gateway/test_chats_controls.py b/core/tests/switch_core/gateway/test_chats_controls.py
index a2c22b4c6..fdf1a6721 100644
--- a/core/tests/switch_core/gateway/test_chats_controls.py
+++ b/core/tests/switch_core/gateway/test_chats_controls.py
@@ -296,3 +296,25 @@ async def test_only_a_failed_or_interrupted_turn_is_retried(chats: _Harness) ->
assert refused.status_code == 409
assert _code(refused) == "NOTHING_TO_RETRY"
assert await _commands(chats, room_id) == []
+
+
+async def test_a_member_is_offered_the_visible_commands_and_no_hidden_one(
+ chats: _Harness,
+) -> None:
+ agent = await chats.agent("helper", owner=chats.alice)
+ room_id = await chats.new_chat(chats.alice, agent, "c1")
+
+ outsider = await chats.client.get(
+ f"/chats/{room_id}/commands", headers=chats.as_user(chats.bob)
+ )
+ assert outsider.status_code == 403
+
+ listed = await chats.client.get(
+ f"/chats/{room_id}/commands", headers=chats.as_user(chats.alice)
+ )
+ assert listed.status_code == 200, listed.text
+ commands = {each["name"]: each for each in listed.json()["commands"]}
+ assert "retry" not in commands
+ assert commands["reset"]["usage"] == "!reset <target>"
+ assert commands["help"]["usage"] == "!help"
+ assert all(each["description"] for each in commands.values())