feat(server): runtime slash commands surfacing MCP prompts and user templates

[rdwj]

Summary

The framework already discovers MCP prompts on connect (_mcp_prompts) but never exposes them to operators. There is also no way for an operator or tenant to add their own commands at runtime without rebuilding the agent's container image. This issue proposes two small REST endpoints and a commands/ directory convention that together give operators a first-class slash-command surface — extending the agent without code or rebuilds.

Motivation

Slash commands are how operators get leverage. Today, every gateway and UI in the stack reinvents its own command parsing (typed text matching, prefixes, autocomplete) on top of the agent's chat-completion API. That pushes operator-extensibility onto the gateway/UI layer when the right home is the agent itself — the agent already knows what MCP prompts are available, what local prompts exist, and what the session state is.

Real use cases:

• A tenant-specific shorthand: /runbook RB-1234 → expands a tenant-specific runbook-search prompt without redeploying the agent.
• A domain workflow: /triage <symptoms> for a healthcare triage agent, expanding to a structured triage prompt with the operator's free-text input substituted in.
• An operator UX: /compact, /fork, /revert shortcuts for the auto-compaction and fork/revert features (separate issues), invoked from the chat surface without going to a separate API console.
• A workshop or demo: instructor pre-loads commands/demo-step-1.md, demo-step-2.md, etc., and runs through a scripted sequence by typing /demo-step-1 etc.

Without a runtime command surface, these all require either a gateway-side lookup table (which then needs to know what each agent supports) or a rebuild of the agent image.

Proposed approach

Two new REST endpoints

• GET /v1/commands — list all available commands with name, description, source (mcp_prompt | local_template | builtin), argument schema.
• POST /v1/commands/{name} — invoke. Body has arguments: dict | list[str] and an optional session_id. The server expands the command into a chat-completion request and runs the agent loop.

Three command sources

1. MCP prompts — already discovered by connect_mcp() and stored in _mcp_prompts. Exposed via get_mcp_prompt() and forwarded as the user message.
2. Local templates — Markdown files with YAML frontmatter under a commands/ directory, mirroring the existing prompts/ shape. Mountable as a ConfigMap so tenants can customise without rebuilding. Substitution: $1..$N for positional arguments, $ARGUMENTS for the full argument string.
3. Builtin commands — /compact, /fork, /revert, etc., when those features are enabled. These are not file-based; they are server-side handlers.

commands/ directory shape

commands/
  runbook.md          # /runbook
  triage.md           # /triage
  demo-step-1.md      # /demo-step-1

A command file:

---
name: runbook
description: \"Search the runbook database by ID.\"
arguments:
  - name: runbook_id
    required: true
    description: \"The runbook identifier (e.g. RB-1234).\"
---

Find runbook $1 and summarise the steps for the operator.
Highlight any preconditions, required permissions, and rollback steps.

The frontmatter is identical to the existing prompts/ convention, which keeps the cognitive overhead low.

Mounting at runtime

The commands/ directory is opt-in. The chart accepts a ConfigMap-mounted volume at /app/commands (or similar). When the directory exists, the server scans on startup and exposes the commands; when it does not, only MCP prompts and builtins are listed.

Open design questions

1. Who can create commands at runtime. Tenant operators only? Authenticated users? The framework should accept identity from kagenti and apply policy — but the policy itself is deployment-specific. Default: read-only (commands are mounted via ConfigMap by an operator with cluster-write rights; the agent itself does not write commands).
2. Composition with the gateway's command surface. If gateway-template already parses /foo syntax, does it route to the agent's commands endpoint, or does it have its own catalog? Likely the gateway should call GET /v1/commands on the agent and forward whatever it finds. Coordinate with that repo's owners.
3. Name collision between MCP prompts and local commands. If both a connected MCP server and the local commands/ directory define a command named triage, who wins? Lean toward local-wins-with-warning, since locals are deployment-scoped and explicit.
4. Argument schema fidelity. MCP prompts have their own argument schemas; local commands have frontmatter argument descriptions. Should GET /v1/commands normalise to a common shape, or surface both as-is? Lean toward normalised shape to reduce client complexity.
5. Streaming. POST /v1/commands/{name} should support SSE streaming (same as chat completions) for operators who want to see the agent work. Easiest path: command invocation is sugar over a chat-completion call; the SSE stream is identical.
6. Builtin command auth. /fork, /revert, /compact map to existing endpoints. Should the slash command go through the same permission checks as the underlying endpoint? Yes — the slash command is a UX shortcut, not a privilege escalation.

Dependencies

• Existing MCP integration (connect_mcp(), _mcp_prompts, get_mcp_prompt()).
• Existing prompts/ convention (Markdown + YAML frontmatter).
• Soft dependencies on auto-compaction (feat(server): auto-compaction on context overflow #166) and fork/revert (feat(server): session fork and revert at the data layer #168) for the builtin command surface; these can be added incrementally as the underlying features land.

Out of scope

• A command marketplace.
• Cross-agent command sharing (each agent's command surface is its own).
• A web UI for editing commands at runtime (the model is mount-via-ConfigMap; UI is ui-template's problem if anyone wants one).
• Command parameterisation by anything other than positional / $ARGUMENTS substitution. Richer templating belongs in MCP prompts, which already support it.

Related

• Existing MCP prompt discovery in connect_mcp().
• prompts/ directory convention.
• Auto-compaction (feat(server): auto-compaction on context overflow #166) — /compact builtin.
• Fork / revert (feat(server): session fork and revert at the data layer #168) — /fork, /revert builtins.
• gateway-template — coordinate routing.