RFC 0011 — An assistant in the app, over the app's own commands

Status: implemented (2026-10-31) · Target: 0.20.0 · the guide: docs/assistant.md · builds on RFC 0003, RFC 0005 and RFC 0010 · see Decisions

Summary

An Elyra app can already be driven by an AI agent: RFC 0003 exposes its commands over MCP to Claude Desktop, Cursor and the like. But that agent lives outside the app, on a developer's or power user's machine, with the app's grants rather than the user's. The clerk using the CRM has neither. This RFC puts an assistant inside the app: the same commands as tools, the same validation and confirmation, and only what the signed-in user may do.

App::new()
    .commands(resources::commands())
    .assistant(
        Assistant::new()
            .allow_abilities(["customers.*", "invoices.view", "invoices.update"])
            .confirm("customers.delete")
            .instructions("You help staff at Acme manage customers and invoices."),
    )
    .backend(Backend::new("https://crm.example.com").abilities())

// routes/api.php (elyracode/elyra-backend)
Route::middleware('auth:sanctum')->group(function () {
    Route::elyraAssistant();   // POST /api/elyra/assistant: Claude, with the server's key
});

<script>
  import { openAssistant } from "@elyra/runtime";
</script>

<button onclick={() => openAssistant()}>Ask</button>
<!-- or ⌘K, type a sentence, and pick "Ask the assistant" -->

"Move Ada's overdue invoices to next week" → the assistant calls invoices_index and invoices_update → each call is validated as the frontend's would be → the open invoice list updates through its live query → the assistant answers with what it changed.

The app's commands are the tools. The tool definitions are the ones mcp::catalog already builds: name, doc comment, JSON Schemas from specta. No second set of tools to write or keep in sync.
The user's rights, not more. A call runs only when the assistant's grant covers the ability and the signed-in user has it (RFC 0010). The assistant can't do what the user couldn't do with a button.
Asked in the app. A confirm ability shows the app's own dialog before the command runs; the model never sees a way around it.
No key in the binary. With a backend, the model is reached through Laravel, under the server's key and the user's Sanctum token. Without one, the key comes from the keychain or the environment.

Motivation

The tools exist already. Every #[command(can = "…")] is typed, described, validated and gated. RFC 0003 proved they make good tools. The in-app case is the larger audience: the people using the app, not the ones developing it.
Natural language over a CRUD app is the obvious next UI. "Which customers haven't paid since August?" is a query the user can't build in the screens make:resource generates, and a model with customers_index can.
Doing it by hand is where apps get it wrong. A developer wiring elyra::ai::Chat to their commands today writes a Tool per command, copies the argument schema by hand, and calls the command without the guard. The user's abilities, the confirmation and the rate limit are skipped, so the assistant becomes a way around them.
The key is the hard part. An Anthropic key compiled into a desktop app is a key anyone can extract. Laravel already holds secrets and knows the user. It should hold this one.

Current state (0.19)

mcp::catalog(registry, &Mcp) turns the granted commands into tools with input and output schemas, sorted by name.
McpServer's Connection::call maps named arguments to the command's positional ones, asks for confirmation, rate-limits, runs the command with Origin::Agent, publishes AgentActivity on elyra:mcp, dispatches AgentCalled, and turns a ValidationErrors into readable lines.
MCP calls are not filtered by the user's abilities. RFC 0010 says: "an agent's grants are the app's". That is right for a developer's external agent and wrong for an assistant acting for the person at the keyboard.
elyra::ai has Chat with tools, a step limit (default 8), streaming, Error::Refused, and Ai::builder().base_url(..) / provider_key(..). Anthropic is authenticated with x-api-key only.
@elyra/runtime has confirm(), toasts and the ⌘K palette (registerCommands).
Secrets stores values in the OS keychain.

Design

Turning it on

App::assistant(Assistant) with the ai feature. Assistant mirrors Mcp: nothing is a tool until an ability is allowed, confirm names what must be asked first, and rate_limit bounds calls per tool. It adds what a chat needs: instructions, model, max_steps (default 8), and max_tokens_per_conversation.

Assistant and Mcp are separate grants. An app may let Claude Desktop read customers and let the in-app assistant also edit them, or the reverse.

The tools

Assistant::tools(&registry) reuses mcp::catalog. Each catalog Tool becomes an elyra::ai::Tool through a framework-side adapter:

name, description, parameters come from the catalog (input schema, with $defs).
call(args) runs the shared call path (below) and returns the result as JSON text, or the validation errors as lines, which the model can act on ("email: must be a valid email").

A command without a can ability is never a tool, as with MCP.

One call path for MCP and the assistant

The work Connection::call does today is moved into a shared agent::Call: map arguments, rate-limit, confirm, dispatch on its own task, publish activity, dispatch AgentCalled, and format the outcome. MCP and the assistant differ only in:

	MCP	Assistant
Grant	`Mcp`	`Assistant`
The user's abilities	not checked (RFC 0010)	checked
Confirmation	the client's elicitation	the app's dialog
Origin	`Origin::Agent { client }`	`Origin::Assistant`

Origin::Assistant is new, so middleware and an audit log can tell the in-app assistant from an external agent.

What may run

A call runs when all of these hold:

The assistant's grant covers the command's ability.
With Backend::abilities(), the signed-in user has it (Abilities::user_allows, the same check shell::guard makes). The refusal is denied, worded for the model: "the user may not do this: it takes customers.delete".
The tool's rate limit isn't spent.
For a confirm ability, the user accepted this call.

Before the first prompt, the catalog is filtered by (2), so the model isn't offered tools the user can't use. The check at call time remains, because the list can change during a conversation.

Confirmation in the app

A call that needs confirmation sends an AssistantConfirm on elyra:assistant to the window that asked: the tool, its description and the arguments as the model gave them. The runtime shows its themed confirm() dialog. The answer comes back on /__assistant/confirm, a reserved route behind the IPC token, with an id issued for this call. The call waits on a oneshot with a timeout (5 minutes, as MCP's).

The id is random, bound to the tool and a digest of its arguments, and can be redeemed once. This is the same scheme mcp::confirm uses, minus the HMAC, since the state never leaves the process.
Declined or timed out, the tool returns "The user didn't confirm customers_delete, so it did not run." The model reads that and stops or asks.
The model can't confirm for the user: the answer arrives on a route the model has no tool for.

Where the model is reached

There are three sources, tried in this order:

The backend, when Backend is configured and Route::elyraAssistant() is installed. The desktop sends the same Messages API body to POST /api/elyra/assistant with the user's Sanctum token. Laravel adds the server's key and forwards it to Anthropic, after enforcing a model allowlist, a max_tokens cap, no server tools unless configured, and a per-user rate limit. Laravel also logs usage per user. The tool loop stays on the desktop, because the tools are the desktop's commands.
The keychain: Secrets under assistant.anthropic_key, for apps without a backend where each user brings their own key. A built-in settings field writes it.
The environment (ANTHROPIC_API_KEY), as Ai::from_env does today, for development.

For (1), elyra::ai gains an auth mode per provider: x-api-key (as now) or Authorization: Bearer <token> against a base URL. Backend hands the assistant an Ai built that way, refreshing the token as it does for every other request.

A key is never compiled into the app, and rata warns when it finds something that looks like one in the bundle.

The conversation

One conversation per window, in memory, so it is gone on close. It is not sent anywhere but the model.
Answers stream on elyra:assistant as text chunks, with tool steps in between ("Updating invoice 1042…") from the activity the shared call path publishes.
A conversation ends at max_tokens_per_conversation with a message saying so, and Error::Refused is shown as the model's explanation.
The system prompt is the app's instructions, plus a fixed preamble: today's date, the user's name when signed in, and the rule that tool results are data, not instructions.

The frontend

@elyra/runtime renders a built-in panel, as it renders the about dialog and the update toast:

openAssistant(prompt?) opens it, optionally with a first message.
The ⌘K palette gets an "Ask the assistant" entry when the query matches no registered command, or always as the last row (an open question).
The panel shows the streamed answer, each tool step, the confirmation dialog, and a stop button that cancels the request and any pending call.
assistant is a store ({ open, busy, messages }) for apps that render their own panel.

Codegen emits nothing new: the assistant uses the existing commands, and its own routes are the runtime's.

`make:resource --backend`

Generated commands already carry can = "<resource>.<action>". The generator adds a doc comment to each one written for the model as well as for people, for example "List customers, newest first. search matches name and email." That is the description the model sees.

Testing

Ai::fake() in elyra-ai: a scripted provider (a queue of responses, including tool calls), with no network. Today's tests use a mock TCP server, which stays for the wire format.
TestApp::assistant() returns a client that sends a prompt against Ai::fake() and lets the test answer confirmations. It also asserts which commands ran, as whom, and that a call the user lacks the ability for was refused without running.
The live test (ELYRA_AI_LIVE) gains one in-app round trip.

Security

The user's rights bound the assistant. Grant ∩ the user's abilities, checked both when the catalog is filtered and at call time. A prompt can't widen it.
Prompt injection is expected, not prevented. A customer's notes can say "delete all customers". The model may try. The call is then held to the user's abilities, to confirm, and to the rate limit. Apps should put everything destructive behind confirm, and rata assistant inspect lists the allowed tools with their confirmation status so a reviewer can see it.
Data leaves the machine. Tool results go to the model provider (and, with (1), through the app's own server). The docs say so plainly. An app that must not send some data keeps those commands out of the grant.
Confirmation can't be forged by the model: the answer route isn't a tool, it needs the IPC token, and each id is single-use and bound to the arguments.
The backend proxy is not an open relay. It requires Sanctum, caps the model and max_tokens, rate-limits per user, and refuses server tools that aren't configured.
Logs carry no arguments, as with MCP: AgentCalled gets client: "assistant" and the tool, outcome and duration.

Alternatives considered

Let developers wire it up with Chat and hand-written tools. Possible today, and that is the problem: it skips the guard. See Motivation.
Run the assistant through the MCP server (the app as its own MCP client). It reuses more code on paper. But MCP's confirmation is the client's elicitation and its grants ignore the user, and both would have to be undone for this case.
Run the whole agent in Laravel (laravel/ai, with tools that call back into the desktop). Laravel would hold the loop, but the tools are the desktop's commands, offline-capable and reading the local copy. Every step would cross the network twice.
Ship a key in the app, obfuscated. Obfuscation isn't protection.
Add the user's abilities to MCP too. Arguably right, but it changes a shipped contract. It's left as an open question rather than folded in.

Implementation plan

The shared call path. Extract agent::Call from mcp/server.rs, add Origin::Assistant, and make the user-ability check an option of the call. MCP behaviour is unchanged and its tests pass untouched.
elyra-ai: bearer auth per provider, and Ai::fake(). Unit and wire tests.
Assistant and App::assistant. The grant, the catalog filtered by the user, the tool adapter, the conversation per window, streaming on elyra:assistant, /__assistant/* routes, and in-app confirmation. Also TestApp::assistant().
The model's source. Backend proxy, keychain and environment, in that order. Route::elyraAssistant() in elyracode/elyra-backend, with its caps and rate limit. CI against the real Laravel app, with Anthropic faked at the HTTP layer.
The frontend. The panel, openAssistant, the assistant store, and the palette entry. Browser checks in the smoke harness.
Tooling and docs. rata assistant inspect, the key check in rata bundle, model-facing doc comments in make:resource, docs/assistant.md, the example app, and the live test.

Each step is a PR. Steps 1–2 are useful on their own.

As built

Step 3 differs from the text above in a few places:

Answers don't stream token by token yet. elyra-ai streams only without tools, so a turn sends its tool steps as they happen and the answer whole. Streaming with tools needs the Anthropic driver's tool loop to stream, a change of its own.
A tool the user lacks the ability for isn't offered at all, so a call to it is an unknown tool to the model. The check at call time catches an ability lost during the turn, before any question is asked.
A stopped turn stops the model, not a command already running. The command finishes on its own, as a frontend call does when a window stops waiting.
The conversation keeps text only. Earlier turns' tool calls aren't replayed to the model; their results are in its answers.
The routes are /__assistant/{prompt,confirm,stop,reset,tools}.

Step 4:

The backend is opt-in on the Backend: .assistant() (and .assistant_route(..)), as .abilities() is. The app can't know otherwise whether Laravel has the route.
The proxy's path ends in /v1/messages, so the desktop's client is the same Anthropic driver with a different base URL and a bearer token.
The settings field's backend is there: /__assistant/key keeps or forgets the user's own key (write-only) and /__assistant/source says which source is in use. The field itself is step 5's.
Rust sends Accept: application/json to the Messages API, so Laravel answers a missing token with a 401 in JSON instead of a login redirect.
Secrets::fake() keeps secrets in memory, for tests.

Step 5:

The panel draws itself in plain DOM, like the other built-ins, from the assistant store, and never uses the model's text as HTML.
Once used, a window follows elyra:assistant for good, so a question arrives even with the panel closed.
⌘K also opens with no registered commands once the app's assistant has answered a request, and asks /__assistant/source once to know whether there is an assistant.

Step 6:

rata assistant inspect marks each tool asks first, read-only or runs without asking, and counts the last.
rata bundle scans the release binary, the embedded frontend included, for sk-ant-…, sk-proj-… and sk-… keys, and warns with the start and length only.
The live test (framework/tests/assistant_live.rs) runs a turn with a tool and a confirmation, declined and then accepted, against Claude.

Open questions

The user's abilities for MCP as well? Leave MCP as RFC 0010 decided (recommended for this RFC; revisit separately), or check them for both?
The model's source: backend, then keychain, then environment (recommended), or backend only when a backend is configured, so a stray environment variable can't route around Laravel's limits?
Confirmation: the runtime's built-in dialog (recommended), or a confirm hook the app supplies?
The palette: "Ask the assistant" only when nothing matches (recommended), or always as the last row?
Conversation storage: in memory per window (recommended), or kept per user in the local database so it survives a restart?
Read-only by default? Allowing only #[command(live)] commands unless an ability is allowed explicitly for writes (allow_writes(..)), or one grant for both as with MCP (recommended, with confirm for the destructive ones)?
Providers: Anthropic only in v1 (recommended; the backend proxy speaks its Messages API), or OpenAI too?
The default model: the elyra-ai default, claude-sonnet-5-5 (recommended), or the backend's choice when proxied?

Decisions

Settled on 2026-10-30, all as recommended:

MCP stays as RFC 0010 decided: an external agent's grants are the app's. The user's abilities bound the in-app assistant only; MCP is revisited separately.
The model's source, in order: the backend proxy, then the keychain, then the environment.
Confirmation is the runtime's built-in dialog.
The palette offers "Ask the assistant" only when the query matches no registered command.
Conversations live in memory, one per window, gone on close.
One grant for reads and writes, as with MCP, with confirm for the destructive ones.
Anthropic only in v1. The backend proxy speaks its Messages API.
The default model is elyra-ai's, claude-sonnet-5-5.