@bernierllc/admin-chat-agent-suite

Drop-in bundle for embedding an LLM-powered admin assistant that can execute privileged actions, stream results, show what changed, and persist conversation history.

One createAdminChatAgent(config) call wires together provider, tools, permissions, persistence, and UI exports.

No Vercel AI SDK anywhere in this package or its dependency graph.

Installation

npm install @bernierllc/admin-chat-agent-suite

Peer dependencies:

npm install react react-dom next
# Optional:
npm install @bernierllc/neverhub-adapter

Usage

import {
  createAdminChatAgent,
  InMemoryConversationStore,
} from '@bernierllc/admin-chat-agent-suite';

// 1. Define your domain tools
const getBookings = {
  name: 'getBookings',
  description: 'Fetch bookings for a date range',
  inputSchema: {
    type: 'object',
    properties: {
      startDate: { type: 'string' },
      endDate: { type: 'string' },
    },
    required: ['startDate'],
  },
  permissions: ['admin:bookings:read'],
  async execute(input: { startDate: string; endDate?: string }) {
    const bookings = await db.bookings.findMany({ where: { date: { gte: input.startDate } } });
    return { success: true, message: `Found ${bookings.length} bookings`, data: bookings };
  },
};

// 2. Wire the suite
const { agent, routeHandler, components } = createAdminChatAgent({
  provider: myOpenAIProvider,     // AIProvider from @bernierllc/ai-provider-core or ai-provider-router
  tools: [getBookings],
  permissionResolver: async (authCtx) => resolvePermissions(authCtx),
  store: new InMemoryConversationStore(),  // Replace with Prisma adapter in production
  maxTurns: 10,
  timeoutMs: 30_000,
});

// 3. Next.js route handler (app/api/chat/admin/route.ts)
export const POST = routeHandler({
  auth: async (request) => {
    const session = await getServerSession(authOptions);
    if (!session?.user) throw new AdminAgentRouteUnauthorizedError('Unauthorized');
    return { userId: session.user.id, orgId: session.user.orgId };
  },
});

// 4. React layout (app/(admin)/layout.tsx)
const { AdminAgentProvider, AdminAgentTrigger, AdminAgentPanel } = components;

export default function AdminLayout({ children }: { children: React.ReactNode }) {
  return (
    <AdminAgentProvider url="/api/chat/admin">
      {children}
      <AdminAgentTrigger position="bottom-right" />
      <AdminAgentPanel />
    </AdminAgentProvider>
  );
}

API Reference

createAdminChatAgent(config)

Creates and returns { agent, routeHandler, components }.

Config (AdminChatAgentConfig = AdminAgentConfig from @bernierllc/admin-agent-service):

| Field | Required | Description | |-------|----------|-------------| | provider | yes | AIProvider instance from @bernierllc/ai-provider-core or @bernierllc/ai-provider-router | | tools | yes | Array of ToolDefinition from @bernierllc/agent-tool-registry | | permissionResolver | yes | (authCtx: AuthContext) => Promise<string[]> | | store | yes | ConversationStore implementation | | systemPromptBuilder | no | (authCtx, orgCtx) => Promise<string> | | maxTurns | no | Max LLM turns per chat (default: 10) | | timeoutMs | no | Per-turn timeout ms (default: 30000) | | rateLimitHook | no | RateLimitHook implementation | | featureGateHook | no | FeatureGateHook implementation |

Return value:

• agent: AdminAgent — Use agent.chat(message, authCtx) directly on the server.
• routeHandler: RouteHandlerFactory — Call with { auth } to get a Next.js POST handler.
• components: AdminChatAgentComponents — All React components and the useAdminAgentChat hook.

Re-exported Components

The components bag (and top-level exports) include:

| Component / Hook | Description | |-----------------|-------------| | AdminAgentProvider | Root React context provider — wrap your admin layout | | AdminAgentTrigger | Floating sparkles button that opens the panel | | AdminAgentPanel | Chat sheet/drawer | | AdminAgentPanelHeader | Panel title bar | | MessageList | Scrollable message history | | MessageBubble | Single message bubble (user or assistant) | | ToolResultCard | Shows tool call success/failure | | ChangeSummaryCard | Renders changeset rollup markdown | | AgentStatusBar | Thinking/executing/idle indicator | | useAdminAgentChat | Hook for programmatic control |

Re-exported Utilities

import {
  InMemoryConversationStore,     // Development-only store
  AdminChatAgentSuiteError,      // Suite-level error
  AdminAgentConfigError,          // From admin-agent-service
  AdminAgentRouteUnauthorizedError, // From admin-agent-nextjs
  // ... all sub-package errors
} from '@bernierllc/admin-chat-agent-suite';

MECE Boundaries

vs. @bernierllc/chat-suite

chat-suite is channel-agnostic human-to-human chat infrastructure: WebSocket connections, message threads, read receipts, presence. No LLM, no tool execution.

admin-chat-agent-suite is an LLM agent embedded in the admin UI that executes privileged domain actions on behalf of the authenticated admin. Zero overlap.

vs. @bernierllc/chat-agent-suite

chat-agent-suite provides support/feedback agents for end-user channels (Slack, in-app support, escalation to human). Persona-driven, flow-based, MCP/RAG access.

admin-chat-agent-suite is an admin-privilege-action agent embedded in the admin dashboard. Tool-execution-driven, permission-scoped, change-tracking, streaming. Different domains, different tools, different UX surface.

Integration Status

Logger Integration

This suite uses @bernierllc/logger throughout all sub-packages. Logging is automatic and requires no configuration. The logger outputs structured JSON and writes to stdout at INFO level by default.

// Logger integration is automatic — no setup needed.
// Set LOG_LEVEL env var to control verbosity: debug | info | warn | error

NeverHub Integration

All service-tier sub-packages auto-detect @bernierllc/neverhub-adapter at runtime and register themselves if NeverHub is available. NeverHub integration is optional — the suite works without it.

// NeverHub integration activates automatically if installed:
// npm install @bernierllc/neverhub-adapter
// No code changes needed; services register themselves on initialize().

Graceful degradation is built in — if NeverHub is not installed or not reachable, the suite continues to operate normally.

No Vercel AI SDK

This suite and all its sub-packages are built on the BernierLLC AI abstraction layer (@bernierllc/ai-provider-core, @bernierllc/ai-provider-router, @bernierllc/ai-agent-runtime). The Vercel AI SDK (ai package) is not used anywhere in this dependency graph.

License

Copyright (c) 2025 Bernier LLC. See LICENSE for terms.