Support registering custom action steps

Open
  • Is something wrong?
#663 1 comment 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
typescript
Domain
api

Research direction

Start by tracing how built-in action steps are parsed and evaluated, how they appear in generated system prompts, and how the Renderer exposes the onAction callback. The issue names no files or tests, so first locate those entry points and check how Action([...]) is handled. Done means registered steps work inside Action, dispatch typed params to the host, appear in prompts, and unknown steps fail clearly.

Written by the indexing model from the issue text.

Description

enhancement

Is your feature request related to a problem? Please describe.

We need app-specific click behavior that does not map cleanly to the built-in action steps (@ToAssistant, @OpenUrl, @Run, @Set, @Reset). In our case, we want the model to say what happens when tapping a card: open a menu, post a message, reset the conversation etc.

Today, unknown @ calls are not evaluated as action steps. We work around this by preprocessing OpenUI Lang before render, rewriting syntax like:

Action([@OpenMenu(["option 1", "option 2"])])

into a plain object literal that our component reads from an action prop. That works, but it is brittle (regex/string rewriting), duplicates knowledge already in the system prompt, and is easy to get wrong while streaming.

Describe the solution you'd like

A public API to register custom action handlers, e.g.:

registerActionStep({
  name: "OpenMenu",
  description: "Opens a menu with the given options",
  props: z.object({
    options: z.array(z.string()),
  }),
  evaluate: (props) => ({
    openMenu(props.options);
  }),
});

Requirements:

  • Registered steps appear in generated system prompts (like built-ins).
  • They can be used inside Action([...]).
  • They dispatch to the host app via onAction (or a similar callback), with a typed params payload.
  • Unknown @ steps fail clearly at parse/eval time instead of being silently dropped.

Describe alternatives you've considered

  • Object literals in props — e.g. { intent: "product_select", name, variantId } on action: z.any(). Works, but is less ergonomic for the LLM and not documented as a first-class action pattern.
  • Component-only handling — custom card components with explicit props instead of Action([...]). More verbose in generated Lang.
  • String preprocessing — rewrite Lang before Renderer. Current approach; fragile and hard to maintain.
  • Always use @ToAssistant — sends a message immediately; cannot support intermediate UI like a product menu.
Dominant language
TypeScript
Stars
10k
Forks
698
Avg merge
1d 3h
Merged PRs (30d)
133

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from thesysdev/openui

All issues in thesysdev/openui

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.