genie
Genie tools for Mastra.
Surfaces each configured Genie space as a small set of flat Mastra
tools the calling agent drives directly - no inner orchestrator
agent. The central agent decomposes user questions, picks which
space to ask, streams the per-turn wire events (status, thinking,
sql, rows) through ctx.writer, and composes the final reply.
Rows are never fetched eagerly: the agent reads a statement’s
values only when it needs to reason about them, otherwise it embeds
a [data:<statement_id>] marker in prose and lets the host UI
resolve the data. Charts are minted asynchronously and referenced
by [chart:<chartId>] markers so prose isn’t blocked on chart
generation; the host UI fetches the cached spec by id once ready.
Space description and serialized-space lookups are available for
grounding when the agent needs schema context.
Each tool’s execute pulls the per-request
WorkspaceClient off ctx.requestContext (stamped by
MastraServer under MASTRA_USER_KEY) and the per-call
writer / abortSignal off ctx, so the tools are stateless
across requests and the central agent owns the loop.
The tools talk to Genie directly via @dbx-tools/genie
(genieEventChat); statement-row fetching is delegated to
fetchStatementData from ./statement.js, which wraps
the workspace statementExecution.getStatement API. AppKit’s
stock genie plugin is honored only for its spaces config
so existing AppKit-style wiring keeps working without change.
Suggested orchestration prompt for the central agent lives in
GENIE_INSTRUCTIONS; compose it into the agent’s own
instructions when you want the canonical “how to drive the
Genie tools” guidance.