CopilotProvider

Code

import { type CopilotEvent, CopilotLauncher, CopilotProvider, type CopilotTransport } from "@fadymondy/nasaq/web";const transport: CopilotTransport = async function* ({ history, message, sessionId }, { signal }) {  const res = await fetch("/api/copilot", {    method: "POST",    body: JSON.stringify({ history, message, sessionId }),    signal,  });  // One JSON event per line, such as {"type":"delta","text":"Hi"}.  const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();  let buffer = "";  for (;;) {    const { value, done } = await reader.read();    if (done) break;    buffer += value;    const lines = buffer.split("\n");    buffer = lines.pop() ?? "";    for (const line of lines) if (line.trim()) yield JSON.parse(line) as CopilotEvent;  }};export function Shell({ children }: { children: React.ReactNode }) {  return (    <CopilotProvider transport={transport} greeting="Hi! Ask me anything." dock={{ launcher: false }}>      <header>        <CopilotLauncher />      </header>      {children}    </CopilotProvider>  );}

AI Assistant · beta

Live examples and controls: CopilotProvider in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/copilot-provider.json

The state behind CopilotChat and CopilotDock. You give it a transport, a function that turns a request into a stream of events, and it does the rest:

• appends the question and a streaming answer;
• applies text, tool steps, sources, artifacts and follow-ups as they arrive;
• stops on demand;
• retries after an error;
• loads and deletes saved sessions.

Any component below it can open the assistant with useCopilot().open(...).

When to useCopy Anchor Link

• An app-wide assistant whose answers stream from your backend (SSE, fetch streams, WebSockets).
• Pages that need to open the assistant with a question or with context, such as "Ask about this order".

When not to useCopy Anchor Link

• A one-off chat with its own state: pass messages and onSend to CopilotChat yourself.
• A single question box: use AskAI.

ImportCopy Anchor Link

import { CopilotProvider, CopilotLauncher, useCopilot } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { type CopilotEvent, CopilotLauncher, CopilotProvider, type CopilotTransport } from "@fadymondy/nasaq/web";

const transport: CopilotTransport = async function* ({ history, message, sessionId }, { signal }) {
  const res = await fetch("/api/copilot", {
    method: "POST",
    body: JSON.stringify({ history, message, sessionId }),
    signal,
  });
  // One JSON event per line, such as {"type":"delta","text":"Hi"}.
  const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = "";
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += value;
    const lines = buffer.split("\n");
    buffer = lines.pop() ?? "";
    for (const line of lines) if (line.trim()) yield JSON.parse(line) as CopilotEvent;
  }
};

export function Shell({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider transport={transport} greeting="Hi! Ask me anything." dock={{ launcher: false }}>
      <header>
        <CopilotLauncher />
      </header>
      {children}
    </CopilotProvider>
  );
}

Anywhere below:

const copilot = useCopilot();

<Button onClick={() => copilot.open({ message: "Summarise this order", autoSend: true, context: [{ id: order.id, label: order.number }] })}>
  Ask AI
</Button>;

AnatomyCopy Anchor Link

CopilotProvider          context only, no DOM
├─ children              useCopilot() works here
└─ CopilotDock           when `dock` is set, wired to the state
CopilotLauncher          data-slot="copilot-launcher"  <button aria-expanded>

APICopy Anchor Link

CopilotProviderCopy Anchor Link

Events (CopilotEvent)Copy Anchor Link

useCopilot()Copy Anchor Link

Returns:

• State: messages, streaming, isOpen.
• Opening: open({ message?, autoSend?, context? }), close, toggle.
• Conversation: send(text, meta?, { hidden?, data? }), stop, retry(answerId?), newChat, feedback.
• Composer: draft / setDraft, context / setContext.
• Sessions: sessionId, sessions, refreshSessions, loadSession, deleteSession.
• Wiring: chatProps, which you spread on your own CopilotChat or CopilotDock.

useOptionalCopilot() returns null outside a provider.

CopilotLauncherCopy Anchor Link

Button props plus:

Pure helpersCopy Anchor Link

The stream logic is exported for tests and custom state:

• reduceStream(state, event) and startAnswer(id), which build up an answer;
• finishAnswer(state), which ends it;
• splitStreamingText(raw), which separates text from artifacts;
• retryPoint(messages, answerId?), which finds the message a retry sends again;
• describeInteraction(kind, detail), which writes the text of a hidden reply.

AccessibilityCopy Anchor Link

• Answers stream into CopilotChat's log region. Errors appear as an alert with a Retry button.
• Stop keeps what arrived and is not reported as an error.
• CopilotLauncher reports aria-expanded and names the shortcut in its title.

RTL & i18nCopy Anchor Link

The launcher label ships in English and Arabic. The text of hidden replies ([action] …, [picked] …) is for the model and is not shown.

Styling & tokensCopy Anchor Link

The provider has no DOM. CopilotLauncher is a Button; style it with variant, size and className.

Do / Don'tCopy Anchor Link

• Do abort the network request when signal aborts, so Stop really stops the server.
• Do yield { type: "session" } once the server saves the conversation, so History and Retry use the right id.
• Don't mount two providers for one assistant; open it from anywhere with useCopilot().

RelatedCopy Anchor Link

• copilot-chat
• copilot-dock
• artifact-renderer

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-ai-assistant-copilot-provider--docs