@luxoai-dev/luxo-assistant
Luxo Assistant
Betav0.8.0The shared assistant surface for LuxoAI products. Declarative tool registry with typed param schemas, surface manifests, bounded prompts, directive parsing, SSE streaming, inline feedback, action telemetry, and a reusable route pattern.
- Package
- @luxoai-dev/luxo-assistant
- Layer
- Assistant shell
- Version
- v0.8.0
- Used by
- SupplyAgent Luxo assistant · LearnAgent Luxo assistant · InvoiceAgent Luxo assistant · future agent surfaces
Architecture
The package sits between the host application and runtime outputs. The host owns auth, data, and side effects; the package validates and shapes flow.
Host
Application workflow
Auth, data, product state, and side effects stay owned by the host app.
Package
Luxo Assistant
The shared assistant surface for LuxoAI products. Declarative tool registry with typed param schemas, surface manifests, bounded prompts, directive parsing, SSE streaming, inline feedback, action telemetry, and a reusable route pattern.
Outcome
Agent outcome
Approved actions, responses, feedback, metrics, or model signals flow back to the product.
Capabilities
The contract surface, summarized.
| Capability | Detail |
|---|---|
| 01 | Declarative tool registry: defineLuxoRegistry + navigateTool / eventTool / guidanceTool, typed params (text, enum, integer, number, boolean). |
| 02 | Auto-generated directive examples in the system prompt so the LLM knows exactly how to call each tool. |
| 03 | Surface manifests so assistants understand where they are embedded. |
| 04 | Bounded prompt construction from product metadata and current page context. |
| 05 | Validated navigation and event directives instead of arbitrary text-triggered side effects. |
| 06 | Risk-aware action confirmation (window.confirm gate for risk: "confirm"; restricted blocked). |
| 07 | Action telemetry: onActionsProposed server hook + createLuxoActionBeaconRoute + actionBeaconEndpoint client prop. |
| 08 | SSE streaming end-to-end (text-delta + reasoning-delta) with transparent buffered fallback. |
| 09 | Inline thumbs/stars feedback per assistant message wired to a shared feedback route. |
| 10 | Optional Supabase-backed persistence, auto-titler, and per-actor quota with blocker UI. |
| 11 | Full manifest i18n for every user-facing string emitted by the route. |
Used by
Concrete consumers in the LuxoAI fleet.
Integration shape
Drop into a host app. The host keeps auth, persistence, and side effects.
import { createLuxoChatRoute } from "@luxoai-dev/luxo-assistant/server";
import {
defineLuxoRegistry,
navigateTool,
enumParam,
} from "@luxoai-dev/luxo-assistant";
const registry = defineLuxoRegistry({
serviceId: "learnagent",
productName: "LearnAgent",
audience: "learners and coaches",
domain: "learning",
defaultSurface: {
key: "review",
label: "Review session",
shortLabel: "Review",
accentLabel: "Learning",
summary: "Review progress and suggest the next exercise.",
tooltip: "Ask Luxo about this learning session.",
paths: ["/review"],
tools: [
navigateTool({
id: "review.open-deck",
label: "Open a deck",
description: "Open one of the learner's saved decks.",
url: ({ slug }) => `/decks/${slug}`,
params: {
slug: enumParam(["algebra", "biology", "history"], {
description: "Deck slug to open.",
required: true,
}),
},
pinned: true,
group: "Learning",
}),
],
},
});
const chat = createLuxoChatRoute({
manifest: registry.manifest,
requireAuth: true,
});
export const GET = chat.GET;
export const POST = chat.POST;
export const DELETE = chat.DELETE;API Reference
Every export, every signature, every parameter. The production-grade reference your code or your agent needs to call this package without reading source.
Open Luxo Assistant API reference