English source · 19 min
Agentic interfaces across independent components
Status, 11 November 2026. The SDK supplies a shared versioned layout registry and current-service read composition. The native workspace consumes that registry after server-side permission checks. The hosted Product Guide shows an app result in both native conversations and presents a cart proposal for shopper confirmation. Try both views and see the hosted acceptance.
The component plan tracks the remaining cross-service renderer and protocol adapters. Independent Checkout owns its session and UI boundary.
A developer should be able to use one Veyndo component with its own interface, embed a focused view in another product, or assemble the complete Veyndo workspace. An agent should use the same operations and UI definitions as the person editing that workspace. Adding a service must not require rewriting navigation, identity, forms or a second agent implementation.
Observed foundations and gaps
| Existing owner | Observed capability | Required extension |
|---|---|---|
src/capabilities/registry.rs and contract.rs |
One native dispatch/input/discovery contract, current admission and conservative agent reads | Flow draft validation publishes a typed result; other native outputs and precise external/financial effects still need per-operation contracts |
Apps model surfaces.rs, view_types.rs, ui_ast.rs |
Strict localized placements, native controls, context/data/action bindings and bounded behavior | Reusable service operation references, shared picker/navigation/results and component compatibility negotiation |
extensions/sdk/browser.js |
Host context/locales, declared actions, resize and nonce-bound results | A documented cross-component host contract for opening resources, selection dialogs, results, cancellation, return and unsaved state |
| Current native admission/preview/release owners | Tenant and actor checks, private preview, reviewed immutable definitions | Same connected path for independent service UI packages and generated workspace proposals |
| Operation/model contracts and SDK generators | Existing shared definitions and transport contracts | Required output DTOs and semantic UI annotations generated consistently, with coverage for every service |
These are specific source observations, not an assertion that every module has completed a security audit. A UI hint never grants access; current server admission and domain invariants remain authoritative.
flowchart LR
D[Registered service operations and controls] --> A[Contextual agent]
A --> V[Validated versioned UI definition]
M[Visual editing] --> V
V --> R[Shared renderer and admitted actions]
R --> S[Standalone service UI]
R --> W[Complete Veyndo workspace]
R --> H[External frontend or MCP host]
Typed results for native tools
The Core operation registry declares the successful result of
automation.validate_flow. MCP tool discovery publishes the schema and Core
checks the result before returning it. The result identifies the draft
revision and confirms the check did not save the Flow. An agent can present
that result in the current draft and offer a separate save action.
The compiled registry produces TypeScript input and result types, OpenAPI schemas keyed by tool name, and an additive WIT interface for typed results. The existing WIT interface still returns JSON strings. Operations without a declared result continue to use their existing response.
Use the SDK 0.4.1 prerelease to consume this result from TypeScript. The installed release package was tested with native MCP discovery, current merchant access and PostgreSQL.
Three delivery modes from one UI owner
Each service repository owns its Rust service and versioned UI package. Its UI package exports focused views and a minimal standalone application. Veyndo imports those same views; it must not maintain a second Payments, Reports or Checkout UI.
| Mode | Example | Composition |
|---|---|---|
| Standalone | Payment review console or checkout in an external storefront | Minimal common shell, service client and admitted identity adapter |
| Embedded | Payment status card in order detail; customer picker in a checkout | Focused UI export with typed host ports; React adapter and Web Component wrapper |
| Agent host | Interactive comparison or review inside a supported assistant | The same admitted operations/UI definition through an MCP Apps adapter |
Trusted first-party packages are reviewed and pinned in the product build, sharing design tokens and the common renderer. Native declarative definitions use registered controls. Arbitrary external app code remains in the existing isolated iframe path with explicit CSP, frame/source/origin policy and scoped message grants. Loading unreviewed remote JavaScript into the privileged administration is not the default.
One definition and a small UI host contract
Extend the existing operation/App Manifest definitions instead of creating another operation registry or permissions list. A component descriptor references:
- Versioned operation identity and input/output DTOs.
- Resource meaning: order, product, customer, checkout, payment or document.
- Registered UI views/controls and permitted data/action bindings.
- Precisely declared read/proposal/write/external/financial effect semantics, preview/review support, replay/idempotency and uncertain-outcome behavior.
- Required/optional component capabilities and compatible API/UI versions.
These are descriptions checked against actual operations. The model cannot declare itself authorized, idempotent or safe to retry. Existing published definitions and fingerprints require backward-compatible defaults or explicit version migrations.
The host supplies API transport, theme, languages, currency formatting, current shop/channel/environment and selected resource context. Context identifies what is being edited; it is not proof of authority. Current permissions and data are resolved server-side. Browser packages receive no privileged service credentials. Independent deployments use their own identity adapter and narrowly scoped, audience-bound access through the service's actual admission path.
A view asks the host to openResource, pickResource, show a review, return a
result or subscribe to changed context. It must not import another service's
router, global store or private components. For example, Payments requests an
order view through a typed resource reference; in Veyndo the host opens order
detail, while an external host can provide its own order adapter. Missing optional
capabilities produce an explicit available alternative. Required dependencies are
checked before activation. Unsaved work, navigation return and cancellation have
one shared lifecycle.
Cross-service business work belongs to the existing durable operation/Flow owners. A sequence of browser events is not a substitute for transaction or saga recovery.
Agent-generated workspaces
The agent receives the current context, admitted operation catalogue, compatible controls, allowed data projections and current work/run state. It produces a validated definition using known controls, operation references and resource bindings. It does not produce unrestricted privileged JavaScript or invent data.
For example, “Explain this customer's delivery problems and prepare the next steps” can produce an order grid, shipment timeline, relevant records and a reviewable proposed action. The person can change filters, edit the layout and save that exact definition as a personal workspace. A reviewed reusable package can later make the same workflow available to other users. Read-only workspace layout and live business changes retain their different authority/release owners.
Manual editing, AI changes and coding-agent proposals use the same revisioned model. Streaming updates may progressively add validated blocks, while stable navigation and existing user edits remain intact. Agent runs expose progress, missing input, cancellation, resumption, budgets, provenance and actual proposals. Each service can use the shared agent runtime through its own tools and identity adapter; it must not require the complete Veyndo Core or copy its own planner.
Public storefront and checkout controls keep a deterministic usable path without an available model. Agent help can configure, explain, prefill and propose; it cannot manufacture a purchase approval or change trusted prices/payment states.
Protocol adapters
- OpenUI can render generated definitions using a supplied component library. Map it to the registered Veyndo catalogue; its output remains untrusted until the shared definition/binding checks pass.
- A2UI describes declarative, updateable agent-generated interfaces. The SDK adapter maps an admitted workspace to the renderer catalog after version negotiation.
- MCP Apps standardizes interactive UI resources in supporting hosts using isolated frames and host communication. Provide progressive fallback to structured/text tool results when the host has no UI support. MCP UI transport never replaces current domain authentication and authorization.
Adapters must declare supported subsets and reject unsupported bindings or effects explicitly. Do not label three independently evolving UI models as one system.
Shared SDK composition
SDK 0.3.0 introduces @veyndo/sdk/composition, independently usable in Node and
browser hosts without React, a database or the Core process. Trusted host code
registers each separately authenticated service and its actual view bindings.
Discovery intersects those bindings with currently exposed read tools. Agents
receive only the available view catalogue and propose a bounded versioned layout;
they cannot introduce endpoints, code, operations or permissions.
A context change aborts reads and discards late results. Changing shop, actor, environment or channel requires new clients and a new composition. A failed service leaves healthy independent views available, with explicit unavailable state. No business writes execute during automatic view loading; existing review controls retain their operation owners. Studio uses the same layout registry and A2UI adapter for its Products, Orders and Customers working views. Native criteria, domain, personal data and intake admission still run before layout projection.
SDK contract and runnable two-service example, implementation, local/native acceptance. This delivers the shared host/layout connection, not all component UI exports, new model runs or completed OpenUI/A2UI/MCP Apps adapters.
Render a shared workspace with A2UI
SDK 0.4.15 adds @veyndo/sdk/a2ui. The host registers component types for
its versioned views and checks the renderer's advertised catalog. The
adapter reuses the current workspace's admission and emits standard A2UI
v1.0 messages for supported views. For a client without the agreed catalog
or a matching binding, it returns structured panel references. Layout
messages carry neither view inputs nor service data. The host reads through
the same scoped SDK client and binds the result to its local component.
Connected Shop uses this adapter with the official Lit renderer. An SDK integration test also assembles a two-service workspace, processes the messages with the official A2UI processor and reads each view from its own MCP endpoint. Studio and Storefront still need the platform-wide adapter integration tracked under UI-06.
Install SDK 0.4.15 · Adapter example · Acceptance.
Open an A2UI working view in Studio
Ask the Studio assistant to show products, orders or customers and open its working view. Studio admits the current user's view and projects it to A2UI v1.0 using the pinned SDK. Its React renderer maps only the registered directory, catalogue intake and shipping policy controls. The same native editor owns the selected record and its unsaved changes.
A client without the Studio catalog falls back to OpenUI for the admitted panels. Neither presentation receives credentials or grants access. The storefront conversation's A2UI integration remains tracked under UI-06.
Orders, shipments and shipping policy
In Studio, ask for open orders and the shipping policy. Open the proposed
working view to see the normal Orders grid and the shipping policy passages
from the current shop. Select a row to reach the original order editor and
its deliveries. The policy panel can also be added or removed from the view.
It requires knowledge.read. Orders retain their own order and personal data
permissions. The policy lookup sends a fixed query in the current language,
excludes app evidence, and never sends an order ID or calls an AI model.
Retry a failed policy read while keeping the order view open.
For a separate application, the Node example
uses @veyndo/sdk/composition to discover and read the existing Commerce
order and the independent Knowledge document search in parallel. Supply
COMMERCE_URL, COMMERCE_ACCESS_TOKEN, KNOWLEDGE_URL,
KNOWLEDGE_ACCESS_TOKEN, WORKSPACE_SHOP and WORKSPACE_ORDER_ID on
the server, then run the example with Node 22 and SDK 0.3.0. Open the
loopback address printed by the example. Use a disposable order and scoped
test credentials. The example projects shipment states and source passages
only, and shows each service failure independently. Shipping booking and
tracking updates remain with their existing owners.
The native storefront assistant also offers a side-by-side comparison of shortlisted products present in the current catalog response. A comparison suggestion opens it directly. It shows the same contextual prices and stock as the product cards. Each product opens the native detail page for variant selection, configuration and the explicit add-to-cart action. Comparison adds no model call and issues no cart writes.
Delivered standalone operation example
The App Runtime service now demonstrates independent HTTP/OpenAPI/MCP schemas with the existing SDK and current external identity. An agent discovers the same typed input/output contract as the HTTP consumer, then invokes bounded evaluation with supplied examples. It receives a fingerprinted simulation result with no applied effect. This supplies one actual operation host; the common generated UI/renderer and cross-service navigation remain the open work described here. Runtime service acceptance.
Reuse across Studio, storefront and external hosts
Studio and the storefront assistant share a Markdown renderer for explanatory text. Tables, lists and emphasis render as React elements. Model-supplied links and images display as text and raw HTML stays inert. The model can suggest products, but prices, stock, product links and purchase controls come from the native catalogue and Checkout. The product comparison is an example of that separation.
Use the same split when extending a surface. A product page can show an explanation next to compatible products and actual availability. An order workspace can pair a delivery explanation with tracking and payment status. Reports can show a short interpretation alongside the actual filtered grid or chart. In each case, register the structured component and its read operation once. Studio, a storefront or an external SDK host can then compose the view from those registered components. The model supplies the explanation and suggests a layout. When a user approves a change, the existing operation checks it.
For partner storefronts, start with the one-page PayPal checkout. The same purchase can be linked from a generated comparison or a conventional product page.
Coverage required from every component
| Component | Useful UI exports and agent compositions |
|---|---|
| Commerce | Product/customer/order pickers, resource detail, explicit command review |
| Checkout | Cart, address/delivery/payment selection, quote and completion; embedded purchase and return |
| Policies | Explainable rule/price comparison and bounded playground; no mandatory chat service for a pure library |
| Knowledge | Source upload, graph/evidence, retrieval/source withdrawal review |
| Catalog AI | CSV/URL intake, mapping, content/media proposal diff and batch progress |
| Agents | Contextual task entry, run/proposal history, review, cancellation and budgets |
| Simulator | Shopper scenario setup, isolated runs and comparison without live effects |
| Apps | Definition/settings/data editor, private preview and version/release review |
| Canvas | Common page/app composition, live renderer, element editing and reference proposal |
| Automation | Graphical rule/Flow editing, event/run inspection and proposed repeatable tasks |
| Connectors | Connection settings, mapping, synchronization state and recovery |
| Migration | Source setup, mapping, progress and reviewed cutover |
| Marketplaces | Listing variants, field mapping, synchronization and imported order exceptions |
| EDI | Profile/mapping, document validation, intake/export and exception review |
| POS | Focused register, customer/product search and explicit receipt/return actions |
| B2B | Company/unit picker, budgets, approvals, quotes and negotiation review |
| Shipping | Delivery selection, booking review, label/tracking and uncertain-effect recovery |
| Reports | Metric/chart/grid definitions, explainable filters and pinned workspace cards |
| Payments | Method configuration, attempt/authorization/capture/refund review and receipts |
| Experience | Existing private original editor and hosted experience, connected through the same host boundary |
| SDK | Typed host clients, React/Web Component examples and adapter conformance tests |
This is the required coverage matrix. It does not mark those exports as delivered.
Acceptance sequence
First implement the shared definition/host ports and extract one actual UI slice, such as a payment detail/review view. Demonstrate it in a minimal external host and inside Veyndo with identical API/revision/current-right behavior. Then generate a reviewable multi-component workspace using those exact exports. Add OpenUI/A2UI and MCP Apps adapters against that proven path. Expand the matrix component by component, using one current contract/renderer/test path.
Every slice needs standalone and product tests, current/foreign/revoked permission cases, missing dependency/version cases, responsive/keyboard/accessibility checks, unsaved/cancel/return behavior and actual rollback/uncertainty controls. A generated screenshot is not acceptance of the underlying service operation.
See independent checkout for its stricter financial and transactional boundaries.
Independent App Data reads
The App Data reader supplies standalone HTTP/OpenAPI/MCP and JavaScript access to installed private App list actions with current rights, a restricted read-only database and signed shop isolation. Native pages share the same query/projection and scope protocol. Complete write/lifecycle hosting and cross-service generated UI remain separate tasks.
Managed portable App records
The optional App Data write profile adds approved package-bound record changes, original state/history rules and atomic events via HTTP/MCP/SDK. Default reader permissions remain separate; native field/reference/ language/commerce policies retain their owners. Full installation, native-resource, settings/jobs and publication hosting remain tracked in the component plan.
App-owned views in the conversation
An installed app can give a read tool its own view. For example, the product guide app can show care instructions as expandable cards inside a shopper's answer. The same package can give the merchant a separate table of merchandising notes with its own permissions. Each result is based on the records returned for that question. The next-page button reads the same app again with the current cursor. When the read action accepts a filter and its visible entity declares an indexed text field with choices, the card or table can filter the results in place. The app declares the labels and choices once. For example, a merchant can select priority merchandising notes while a shopper filters public care instructions. Both controls use the same app list action.
Try the Product Guide package
in a private shop. Install it, add a few records linked to a catalog product and
ask the shop assistant for its care instructions. Ask Studio for merchandising
notes to see the private view. A compatible MCP Apps host can also find the
resource through the tool's _meta.ui.resourceUri and read it with
resources/read. Clients that use text tools still receive the ordinary tool
result. MCP Apps specification.
The package declares a native view at storefront.assistant or admin.assistant
and binds it to one explicitly enabled MCP list action. Use a public action and
entity for the shopper. Use a private action with the necessary team scopes for
Studio. The declared text, tables and cards define the view. Veyndo derives the
attachment from the tool it actually executed, opens it in an isolated frame and
sends the call's arguments and structured result. A page request can only rerun
that view's own list tool. Veyndo keeps the original arguments and can add one
declared choice. For example, a product ID already in the tool's filter stays
fixed when someone changes the category. The current tenant, active package
revision, sales channel and action rights still apply. The app frame receives no session token.
After disabling the app, subsequent reads of its resource are rejected, including from earlier conversations.
This path covers installed Veyndo packages with declarative read views.
resources/read is also available to external clients that support MCP Apps.
The card can appear while the assistant prepares the text in both Studio and
the shop. Studio uses the saved run. The shop uses its existing chat stream.
Show the shopper's app view during the answer
The shop requests text/event-stream on the same POST /api/concierge route.
An app-views event carries up to three views from completed public tool
reads. The browser can load and filter a card through the existing MCP host
while the answer is pending. Shoppers can also carry their chosen filter into
the editable draft for their next message. The complete event contains the
full verified answer. Each view keeps its attachment ID so the shop preserves
the loaded card and its filter when the explanation arrives. Cart review becomes
available when the answer completes. The shopper still explicitly confirms
any cart change.
Clients that request ordinary JSON receive the original response shape with the final attachments. When the shop leaves the chat or changes its context, it cancels the pending stream. The server keeps its inference limit throughout the stream and authorizes the card's separate read requests in their current shop and channel.
Run a guide and Checkout in an external host
Connected Shop uses the published JavaScript SDK 0.4.6 to read a Veyndo product, discover the installed MCP App and complete a reviewed simulated purchase through independent Checkout. The official AppBridge presents the resource in an isolated iframe. The host fixes the tool and product and accepts only its declared filter. The browser receives no Commerce credential. A fixed guide question makes the sample runnable without a model key. Its purchase uses the same order and stock transaction as the native shop.
The Product Guide stays on the parent product while the host can review a variant. Switching the selection clears the displayed offer. Each fresh review binds the confirmation to the selected variant, total and Core cart revision. The Node host uses the typed cart preview and apply calls to prepare that review, and the typed receipt lookup to recover the order after a lost reply. Desktop and mobile acceptance.
Compare OpenUI and A2UI
Choose a renderer at the top of Connected Shop. The example host converts one admitted panel order into OpenUI Lang or standard A2UI v1.0 JSON. The A2UI path uses the official Lit renderer and registers the same two panel types. An optional model response selects which panel comes first. It receives only the requested focus. The installed MCP App retains its product and filter scope, and Core prices and confirms the selected variant through independent Checkout in either layout.
Run the SDK example · Browser acceptance · A2UI v1.0 specification.
Show the merchant's app view during the answer
Read tools backed by an admitted App view tell the model that they supply an
interactive result. The shared merchant/shopper read owner reserves a final
answer after at most three read rounds. It retains the actual tool results and
view references instead of failing a fourth request for more reads. The final
model call has no tools and must identify missing evidence. Existing rights,
source checks, durable checkpoints and approval requirements still apply.
The local app_surfaces regression exercises a model that keeps asking for
reads: three App reads produce a fourth, tool-free answer with the private
table and unchanged product state. The same exhausted-budget case also runs
through the shopper path: its catalogue has no private read tool, and neither
its transcript nor its App results contain the private merchant notes. Hosted
model selection is tested separately.
The Studio chat polls its existing saved run. For a running conversation,
GET /api/agent/runs/{id} can return up to three appViews references with
their attachment ID, revision-bound resource URI and original tool arguments.
The run status admits the original actor and checks the permissions recorded
when the run began. The app card loads the resource and makes its scoped read
with current access through /mcp. Polling carries no app result rows and does
not rerun the model or query the app. A worker taking over a run clears the
published references and rebuilds them from revalidated reads.
The card remains mounted when Studio loads the completed message. Its filter stays selected. The merchant can carry the verified filter into the editable follow-up while the run is active and send it once the current answer finishes. Only the finished message can show the native proposal for approval.
One capability, two ways to present it
The Product Guide tutorial walks through installing one app, using its separate shopper and merchant views, and exercising both read tools from an external JavaScript client.
MCP Apps is the protocol between a chat host and an app view. The host reads the resource declared by the tool, initializes the isolated view, delivers tool arguments and results, and mediates subsequent tool calls. OpenUI describes the components to render as a model streams a layout. An MCP App can use OpenUI inside its frame. The native Veyndo workspace can also use OpenUI without an MCP frame. Both can bind to the same typed service operations. MCP Apps lifecycle · OpenUI.
Review and act in the Veyndo chat
When an app result points to one product through a declared catalogue reference, the storefront chat offers the native variant picker next to the app. The shopper selects a variant, checks the price and estimated delivery, then explicitly adds it. A quote request calculates the proposed cart without saving it. Confirmation uses the original cart revision and a fingerprint of the reviewed result. If the cart or the recalculated quote has changed, the shopper has to review it again.
In Studio, an app result can accompany a saved catalogue proposal. Open Review proposed change to compare the current and proposed value, then approve it with the original merchant session. Core checks the current rights and original product revision. Both controls are owned by Veyndo's chat host. The app frame continues to call its declared read action.
Storefront developers can use POST /store-api/checkout/cart/preview with the
current cart token and {revision, items}. To confirm, send the same revision
and items plus the returned review value to the existing cart PUT route.
Treat an HTTP 409 as a request to fetch and review the current cart again.
Use a filter in the next message
After applying an app filter, choose Use filter in chat. The view sends
ui/update-model-context with its tool name, filter field and selected value.
Veyndo accepts only the last filter that the host successfully ran for that
frame. It inserts the verified identifiers into the editable draft in Studio
or the storefront. The shopper or merchant can change or remove the text
before sending. The message carries no app records, credentials or free-form
instructions from the frame. The next turn runs with the current rights of the
same chat. Hosts without the structured context capability hide this control.
Nord Atelier demonstrates streaming OpenUI and the same catalogue and cart preview APIs in a separate storefront. Embedding its interaction in an external MCP Apps host is still open. Client support.