ai message queue.md

AI Message Queue

Installation

npx shadcn@latest add @kokonutui/ai-message-queue

Props

Prop Type Default Description
title? string "Auth refactor"
initialPrompt? string The message the agent is working on when the component mounts. The demo's when respond is left out.
initialQueue? string[] Follow-ups already waiting in the queue.
respond? (text: string, signal: AbortSignal) => AgentResponse | AsyncIterable<AgentUpdate> Runs the agent on a message. Return a stream of updates (steps as they start, reply text as it comes) and the run follows it, ending when the stream does. Stop and Send now abort signal; a throw ends the run with the error's message. Or return fixed steps and a reply, played on stepMs. Demo when omitted.
onQueueChange? (queue: QueuedMessage[]) => void Called with the queue whenever it changes, to keep it across reloads.
stepMs? number 1700 Milliseconds per step of a run with fixed steps.
className? string Extra classes for the root element.

AgentResponse

Field Type Description
steps string[] What the agent shows while it works, one line per step.
reply string

AgentUpdate

One update from a live run: a step starts a new line of work (the one before it is done), a text adds to the reply.

type AgentUpdate = { step: string } | { text: string };

QueuedMessage

Field Type Description
id string
text string

Usage

Pass respond to run your agent. It gets the message and a signal, and returns a stream of updates: { step } when a new piece of work starts and { text } as the reply comes in. The run ends when the stream does, and the next queued message goes in. Stop and Send now abort the signal; a throw ends the run with the error's message. onQueueChange hands you the queue on every edit, so it can survive a reload. Without respond, the demo plays with its own prompt and queue.

"use client";

import type { UIMessageChunk } from "ai";
import AIMessageQueue, { type AgentUpdate } from "@/components/kokonutui/ai-message-queue";

/** Turns your agent route's UI message stream into steps and reply text. */
async function* runAgent(text: string, signal: AbortSignal): AsyncIterable<AgentUpdate> {
  const res = await fetch("/api/agent", {
    method: "POST",
    body: JSON.stringify({ text }),
    signal,
  });
  if (!(res.ok && res.body)) {
    throw new Error("The agent didn't start. Try again.");
  }
  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  while (true) {
    const { done, value } = await reader.read();
    if (done) return;
    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop() ?? "";
    for (const line of lines) {
      if (!line.startsWith("data: ") || line === "data: [DONE]") continue;
      const chunk = JSON.parse(line.slice(6)) as UIMessageChunk;
      if (chunk.type === "tool-input-available") yield { step: chunk.toolName };
      if (chunk.type === "text-delta") yield { text: chunk.delta };
      if (chunk.type === "error") throw new Error(chunk.errorText);
    }
  }
}

export function AgentPanel() {
  return <AIMessageQueue respond={runAgent} title="Auth refactor" />;
}

Your route returns streamText({ ... }).toUIMessageStreamResponse(). Map tool names to readable lines ("Reading session.ts") in the same loop.