# AI Message Queue

## Installation

```bash
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.

```ts
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.

```tsx
"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.
