Debug Actions experimental
Debug Actions turns an app's debug menu into typed actions the JetWhale host and AI agents can run: sign in as a test user, reset onboarding, shift the clock, open a deep link. The app declares each action once; the host builds a form for its arguments, and an agent gets the same action with a JSON Schema over MCP.
Works with: Android, iOS, macOS, desktop (JVM) and the web.


Setup
Install the host plugin
Install Debug Actions from Settings → Plugins → Add Plugins → Official Plugins. To install it by Maven coordinates or from a file, see Host Settings → Plugins.
Add the agent to your app
dependencies {
implementation("com.kitakkun.jetwhale:jetwhale-agent-runtime:<version>")
implementation("com.kitakkun.jetwhale:jetwhale-debug-actions-agent:<version>")
// Only for actions that belong to a screen:
implementation("com.kitakkun.jetwhale:jetwhale-debug-actions-agent-compose:<version>")
}The agent API is marked @ExperimentalJetWhaleApi and may change between releases; opt in with @OptIn(ExperimentalJetWhaleApi::class) where you use it.
val actionsPlugin = JetWhaleDebugActionsAgentPlugin()
actionsPlugin.register {
action("Reset onboarding") {
perform { onboarding.reset() }
}
}
startJetWhale { plugins { register(actionsPlugin) } }Declaring actions
An action's arguments are one @Serializable class. Its properties become the fields of the host's form and of the MCP schema; a property with a default may be left out, and @McpDescription documents it for people and agents alike.
@Serializable
data class SignIn(
@McpDescription("The test account's address.")
val email: String,
val tier: Tier = Tier.FREE,
)
actionsPlugin.register {
group("Account") {
action<SignIn>("Sign in as test user") {
description = "Replaces the session with a test account."
options("email") { testAccounts.map { it.email } }
perform { args -> auth.signIn(args.email, args.tier) }
}
}
}| Setting | What it does |
|---|---|
description | Shown under the title and to agents |
options(property) { … } | Suggested values for a property, fetched from the app each time |
destructive = true | The host asks before running; an agent must pass confirmDestructive: true |
runsOnMainThread = true | Runs on Dispatchers.Main, for UI objects bound to the main thread (Compose state does not need it; on the JVM the app needs a Dispatchers.Main provider such as kotlinx-coroutines-swing) |
timeout | How long a run may take (30 seconds unless set) |
The value perform returns is shown to whoever ran it: a String as text, a JsonElement as JSON, anything else through toString(), and a thrown exception with its stack trace. An action can therefore answer a question — "what is the current user id?" — rather than change anything.
Properties are entered by type: text for strings and numbers, a switch for a Boolean, a menu for an enum, and JSON for anything else (lists, nested classes).
Actions of a screen
With the Compose artifact, a composable registers actions that exist only while it is shown:
@Composable
fun CheckoutScreen(form: CheckoutFormState) {
actionsPlugin.DebugActions(form) {
action("Fill test card") { perform { form.fill(TestCards.visa) } }
}
}The host marks them Screen, and they appear and disappear as the user navigates. Pass what the actions capture as keys; they are declared again when a key changes.
Using it
- Search — ⌘K (Ctrl+K) focuses the search field; Enter picks the first match.
- Pins — pinned actions stay at the top of the list, across restarts.
- Arguments — the form starts from the arguments the action last ran with.
- Runs — the latest result under the form, and the action's recent runs, including those an AI agent made. A run in progress can be canceled.
MCP tools
With the MCP server running, an AI agent runs the same actions through these tools. Each takes the sessionId of the app's session.
| Tool | What it does |
|---|---|
com.kitakkun.jetwhale.actions.listActions | Every action with its argument JSON Schema, suggested values, and whether it is destructive or belongs to the current screen |
com.kitakkun.jetwhale.actions.runAction | Runs an action by id with arguments; returns the outcome, the result and any error with its stack trace |
While an agent runs either tool, the action list is ringed.
Limits
- Actions are not tools of their own. The tool list of an MCP connection is fixed when it opens, while screen actions come and go, so an agent lists the actions and runs one by id. List again after navigating.
- A run that outlives its
timeout(30 seconds unless the action sets one) is canceled and reported as timed out.