@adonis-agora/agent 0.65.1 → 0.66.1

package/dist/src/turn-frames.js

@@ -33,6 +33,11 @@ export function observeTurnFrames(writer, now = Date.now) {
             return;
         }
         closeBurst();
+        // A preview of a call's streaming input is shown, never kept: the call's own push is.
+        if ((frame.t === 'component' && frame.partial === true) ||
+            (frame.t === 'event' && frame.event.kind === 'ui' && frame.event.partial === true)) {
+            return;
+        }
         // A repeat id replaces the props but keeps the component where it first appeared, exactly as
         // the client's data part does.
         if (frame.t === 'event' && frame.event.kind === 'ui') {

package/dist/src/turn-frames.js.map

@@ -1 +1 @@
-{"version":3,"file":"turn-frames.js","sourceRoot":"","sources":["../../src/turn-frames.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"turn-frames.js","sourceRoot":"","sources":["../../src/turn-frames.ts"],"names":[],"mappings":"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"}

package/dist/stubs/config/agent.stub

@@ -6,6 +6,8 @@ import { defineConfig, stores } from '@adonis-agora/agent'
 // import { attachmentStores } from '@adonis-agora/agent'
 // import { aiSdkModel } from '@adonis-agora/agent/ai-sdk'
 // import { openai } from '@ai-sdk/openai'
+// import { defineCatalog, genui } from '@adonis-agora/agent/genui'
+// import { BUILTIN_COMPONENTS, LAYOUT_COMPONENTS } from '@adonis-agora/agent/genui/builtins'
 
 /**
  * Configuration for @adonis-agora/agent. Only \`model\` is required. Pick a \`store\` by name from the
@@ -21,10 +23,10 @@ export default defineConfig({
    * The LLM provider. Wrap the Vercel AI SDK via \`aiSdkModel(...)\` (from \`@adonis-agora/agent/ai-sdk\`)
    * or supply any \`ModelProvider\`. A lazy thunk keeps the provider SDK peer imported only at boot:
    *
-   *   model: () => aiSdkModel({ model: openai('gpt-4o-mini') }),
+   *   model: () => aiSdkModel(openai('gpt-4o-mini')),
    */
   model: () => {
-    throw new Error('Configure a model in config/agent.ts (e.g. aiSdkModel({ model: ... }))')
+    throw new Error('Configure a model in config/agent.ts (e.g. aiSdkModel(openai(...)))')
   },
 
   store: 'lucid',
@@ -53,6 +55,12 @@ export default defineConfig({
   // disk). Mounts POST /agent/attachments; a send names uploads as { mediaId }, resolved server-side.
   // attachments: attachmentStores.media(),
 
+  // Generative UI: the model composes catalog components (tables, charts, cards, …) into one
+  // \`ui__render\` tree, validated before it streams; your client renders each by name. Keep the
+  // catalog in its own file to share it with the browser. \`mode: 'per-component'\` gives one
+  // \`ui__show_*\` tool per component instead.
+  // genui: genui({ catalog: defineCatalog([...BUILTIN_COMPONENTS, ...LAYOUT_COMPONENTS]) }),
+
   // The implicit default agent (base prompt, personas, tool allow-list). Omit for a bare assistant.
   // defaultAgent: {
   //   systemPrompt: 'You are a helpful assistant.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.65.1",
+  "version": "0.66.1",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {

package/skills/agent-setup/SKILL.md

@@ -315,6 +315,16 @@ Agora owns its catalog (`@adonis-agora/agent/genui`), browser rendering
 (`@adonis-agora/agent/react/media`). Protocol compatibility does not require installing
 Aviary packages.
 
+`genui({ catalog })` in `config/agent.ts` registers ONE model tool, `ui__render`, taking a
+component tree (`{ type, props, children? }`; a single node is a valid tree and is pushed as
+that component). Its input schema is exact per component. Put `LAYOUT_COMPONENTS` (`Stack`,
+`Card`, …) in the catalog next to `BUILTIN_COMPONENTS` and register a React renderer for each
+layout you use. `mode: 'per-component'` instead registers one `ui__show_<component>` tool per
+standalone component — for small models or when each tool should carry its own exact schema.
+`streaming: 'partial'` draws the tree while the model writes it; renderers then read
+`useGenuiNode()?.incomplete` and must tolerate half-written props. Source:
+`packages/adonis/docs/generative-ui.mdx`.
+
 For static HTML, use `createReactComponentRegistry` and `createReactServerRenderer` from
 `@adonis-agora/agent/react/genui/server`; install matching `react` and `react-dom` peers.
 Keep this server entry out of browser bundles: it reads trusted filesystem stylesheets

package/skills/agent-testing/SKILL.md

@@ -78,7 +78,9 @@ Source: `packages/adonis/README.md` ("Framework-agnostic core"),
 ### Pattern 1 — script a tool-call round-trip
 
 `FakeModelProvider` takes a script — a pure function of `(args, turnIndex)`. `turnIndex`
-counts assistant turns already in history, so there is no internal counter to reset:
+counts assistant turns already in history, so there is no internal counter to reset. A tool
+call's id is `call-<turnIndex>-<name>`, with a `-2`, `-3`… suffix when that provider instance
+already issued it (another thread's same turn), so one provider can serve many threads:
 
 ```ts
 import { FakeModelProvider } from '@adonis-agora/agent/testing'

package/skills/agent-tools/SKILL.md

@@ -241,6 +241,14 @@ export const listRecords = defineTool({
 `table` and `chart` present the builtin `DataTable` and `Chart` definitions: put them in the
 genui catalog (`BUILTIN_COMPONENTS` from `@adonis-agora/agent/genui/builtins`, or the two
 definitions) and register app renderers under those names. Builtins carry no visuals.
+`genui({ catalog })` also offers the model one `ui__render` tree tool over that catalog (the
+default mode; `mode: 'per-component'` gives `ui__show_*` tools instead).
+A tool that knows its component before it reads can push a skeleton first: `ctx.emitUi(name,
+{ state: 'loading', … })`, then the data with `{ id }` from that push (the component's props
+schema must accept the placeholder variant; mark it `internal: true`). Always end on that id
+(data, `empty` or `error`), and only push the skeleton when the component is declared in
+`ctx.uiCapabilities` and `ctx.pageContext.channel` is unset. A tool that throws persists none
+of its pushes. See `packages/adonis/docs/genui-loading-states.mdx`.
 Use `createComponent` for custom definitions and one `createComponentRegistry` per app
 or tenant. Input `props` may transform; if the transform changes shape or is not
 idempotent, declare `outputProps` to validate the normalized JSON persisted in frames.
@@ -267,10 +275,13 @@ canUse(actor: Actor) { return this.plans.includesDocs(actor.tenantRef) }
 
 `defineTool` / `defineConfirmedTool` take `enabled` and `canUse` as options; `mcpServers[]`
 takes both per server. Order on the offered list AND on invoke: allow-list → `enabled` →
-`RolesPolicy` → `canUse`; none can widen. A disabled tool is never shown to the model and
-invoking one throws `ToolDisabledError` (not `ToolForbiddenError`). Prefer these to registering a
+`RolesPolicy` → `canUse`; none can widen. `invoke` additionally re-asks `describe()` with the
+call's actor, thread, agent and `uiCapabilities`: a tool answering `available: false` for that
+scope was never offered, and calling it anyway throws `ToolNotFoundError`. A disabled tool is
+never shown to the model and invoking one throws `ToolDisabledError` (not `ToolForbiddenError`). Prefer these to registering a
 tool conditionally, and to refusing inside `execute` (which costs the model a turn).
-Source: `packages/adonis/docs/authoring/tools.mdx`, `packages/adonis/src/tool-filters.ts`.
+Source: `packages/adonis/docs/authoring/tools.mdx`, `packages/adonis/src/tool-filters.ts`,
+`packages/adonis/src/tool-registry.ts` (`validated`, `describeScopeOf`).
 
 ## Common mistakes