@agentic-kit/react 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# @agentic-kit/react
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/agentic-kit/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/agentic-kit/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/agentic-kit/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@agentic-kit/react"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/agentic-kit?filename=packages%2Freact%2Fpackage.json"/></a>
+</p>
+
+Headless React bindings for `@agentic-kit/agent`. Exposes a single hook —
+`useChat` — that POSTs messages to a server endpoint, parses the SSE stream
+back into typed `AgentEvent`s, and folds them into a `Message[]` plus a
+small set of derived states (streaming snapshot, executing tools, pending
+decisions).
+
+The hook ships no UI. State lives in messages — there is no separate run
+store and no `runId` to keep in sync.
+
+## Installation
+
+```bash
+npm install @agentic-kit/react @agentic-kit/agent agentic-kit
+```
+
+Peer-deps `react@>=18` and `react-dom@>=18`.
+
+## Server Contract
+
+`useChat` POSTs JSON of the shape `{ messages, ...body() }` to `api`, and
+expects an SSE response whose `data:` frames decode to `AgentEvent`s. The
+easiest way to produce that is `AgentRunHandle#toResponse()`:
+
+```ts
+// app/api/chat/route.ts (Next.js)
+import { Agent } from '@agentic-kit/agent';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const agent = new Agent({ initialState: { model, tools, systemPrompt } });
+  agent.replaceMessages(messages.slice(0, -1));
+  return agent.prompt(messages[messages.length - 1]).toResponse();
+}
+```
+
+## Usage
+
+```tsx
+import { useChat } from '@agentic-kit/react';
+
+export function Chat() {
+  const {
+    messages,
+    streamingMessage,
+    isStreaming,
+    pendingDecisions,
+    executingToolCallIds,
+    send,
+    respondWithDecision,
+    abort,
+  } = useChat({ api: '/api/chat' });
+
+  return (
+    <div>
+      {messages.map((m, i) => <MessageView key={i} message={m} />)}
+      {streamingMessage && <MessageView message={streamingMessage} streaming />}
+
+      {[...pendingDecisions.values()].map((pending) => (
+        <DecisionPrompt
+          key={pending.toolCallId}
+          event={pending}
+          onApprove={() => respondWithDecision(pending.toolCallId, { approved: true })}
+          onDeny={() => respondWithDecision(pending.toolCallId, { approved: false })}
+        />
+      ))}
+
+      <Composer onSubmit={send} disabled={isStreaming} onAbort={abort} />
+    </div>
+  );
+}
+```
+
+## API
+
+### `useChat(options): UseChatResult`
+
+#### Options
+
+- `api` — endpoint to POST messages to.
+- `body?: () => Record<string, unknown>` — extra fields merged into each
+  request body (e.g. model id, conversation id).
+- `initialMessages?: Message[]` — starting message log.
+- `fetch?: typeof globalThis.fetch` — inject a custom fetch (useful for
+  auth headers, tests).
+- `onMessage?(message)` — fired for each finalized message (assistant or
+  toolResult).
+- `onFinish?(assistant)` — fired once per run with the final assistant
+  message.
+- `onDecisionPending?(event)` — fired when a tool pauses awaiting a decision.
+- `onToolExecutionStart?(event)` — fired when a tool begins running.
+- `onToolExecutionEnd?(event)` — fired when a tool finishes (or errors).
+- `onError?(err)` — fired on transport or server errors.
+
+#### Result state
+
+- `messages: Message[]` — committed log.
+- `streamingMessage: AssistantMessage | null` — the in-flight assistant
+  message being streamed, including any partial tool-call blocks.
+- `isStreaming: boolean`.
+- `pendingDecisions: ReadonlyMap<string, ToolDecisionPendingEvent>` — keyed
+  by `toolCallId`.
+- `executingToolCallIds: ReadonlySet<string>` — tool calls currently running
+  on the server.
+- `error: unknown`.
+
+#### Result actions
+
+- `send(input: string | Message)` — append a user message and run.
+- `sendMessages(msgs: Message[])` — replace the local log and run with that
+  exact list. Useful when the caller has already prepared a transcript.
+- `setMessages(update)` — patch messages without sending. Accepts an array
+  or `(prev) => next`. Recomputes `pendingDecisions` from the new log.
+- `respondWithDecision(toolCallId, value)` — attach a decision to the
+  matching pending `toolCall` block and re-POST. Walks the log backwards to
+  find the most recent assistant message owning that id with no decision
+  yet, so the caller is free to append unrelated messages between the pause
+  and the user's response. Throws if no pending match is found.
+- `abort()` — cancel the in-flight request. Visible text in the streaming
+  message is preserved as a finalized assistant message; orphan tool-call
+  blocks are dropped so they don't re-pause the run on the next call.
+
+## Patterns
+
+### User types instead of clicking approve/deny
+
+If the UI lets the user send a new message while a tool is paused, the
+server can't resume on text alone — every dangling `toolCall` needs a
+result before the next request. Compose `injectDeferralResults` from
+`agentic-kit` with `sendMessages`:
+
+```ts
+import { injectDeferralResults, createUserMessage } from 'agentic-kit';
+
+await sendMessages([
+  ...injectDeferralResults(messages),
+  createUserMessage(text),
+]);
+```
+
+That synthesizes a stand-in `toolResult` for each paused tool call so the
+transcript is well-formed when the server picks it back up.
+
+---
+
+## Related Constructive Tooling
+
+### 🤖 AI & Agent Development
+
+* [agentic-kit](https://github.com/constructive-io/agentic-kit): **🧰 Provider-agnostic LLM adapter** with streaming and multi-turn support. Swap between Anthropic, OpenAI, Ollama, and any OpenAI-compatible endpoint.
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.d.ts

@@ -0,0 +1 @@
+export { type ToolDecisionPendingEvent, useChat, type UseChatOptions, type UseChatResult, } from './use-chat.js';

package/esm/index.js

@@ -0,0 +1 @@
+export { useChat, } from './use-chat.js';

package/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/esm/use-chat.d.ts

@@ -0,0 +1,42 @@
+import type { AgentEvent, AgentToolResult } from '@agentic-kit/agent';
+import type { AssistantMessage, Message } from 'agentic-kit';
+export type ToolDecisionPendingEvent = Extract<AgentEvent, {
+    type: 'tool_decision_pending';
+}>;
+export interface ToolExecutionStartEvent {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export interface ToolExecutionEndEvent {
+    toolCallId: string;
+    toolName: string;
+    result: AgentToolResult;
+    isError: boolean;
+}
+export interface UseChatOptions {
+    api: string;
+    body?: () => Record<string, unknown>;
+    initialMessages?: Message[];
+    fetch?: typeof globalThis.fetch;
+    onMessage?: (message: Message) => void;
+    onFinish?: (message: AssistantMessage) => void;
+    onDecisionPending?: (event: ToolDecisionPendingEvent) => void;
+    onToolExecutionStart?: (event: ToolExecutionStartEvent) => void;
+    onToolExecutionEnd?: (event: ToolExecutionEndEvent) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseChatResult {
+    messages: Message[];
+    streamingMessage: AssistantMessage | null;
+    isStreaming: boolean;
+    pendingDecisions: ReadonlyMap<string, ToolDecisionPendingEvent>;
+    executingToolCallIds: ReadonlySet<string>;
+    error: unknown;
+    send: (input: string | Message) => Promise<void>;
+    sendMessages: (messages: Message[]) => Promise<void>;
+    setMessages: (msgs: Message[] | ((prev: Message[]) => Message[])) => void;
+    respondWithDecision: (toolCallId: string, value: unknown) => Promise<void>;
+    abort: () => void;
+}
+export declare function useChat(options: UseChatOptions): UseChatResult;

package/esm/use-chat.js

@@ -0,0 +1,331 @@
+import { parseSSEStream } from '@agentic-kit/agent';
+import { createUserMessage } from 'agentic-kit';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+/**
+ * Compute the pendingDecisions map from a messages array. A toolCall counts as
+ * pending when it has neither a `decision` field nor a paired `toolResult`.
+ *
+ * Used on `setMessages` to recompute server-derived state from the new array.
+ * The synthesized event is a stub (no `input`, no `schema`) — the original
+ * decision-pending event is not recoverable from messages alone, but the map
+ * key (toolCallId) is what consumers actually need to render decision UI.
+ */
+function rederivePendingDecisions(messages) {
+    const completed = new Set();
+    for (const m of messages) {
+        if (m.role === 'toolResult')
+            completed.add(m.toolCallId);
+    }
+    const pending = new Map();
+    for (const m of messages) {
+        if (m.role !== 'assistant')
+            continue;
+        for (const block of m.content) {
+            if (block.type !== 'toolCall')
+                continue;
+            if (completed.has(block.id))
+                continue;
+            if ('decision' in block && block.decision !== undefined)
+                continue;
+            pending.set(block.id, {
+                type: 'tool_decision_pending',
+                toolCallId: block.id,
+                toolName: block.name,
+                input: block.arguments,
+                schema: { type: 'object' },
+            });
+        }
+    }
+    return pending;
+}
+export function useChat(options) {
+    const [messages, setMessagesState] = useState(() => options.initialMessages ?? []);
+    const [streamingMessage, setStreamingMessage] = useState(null);
+    const [isStreaming, setIsStreaming] = useState(false);
+    const [pendingDecisions, setPendingDecisions] = useState(() => rederivePendingDecisions(options.initialMessages ?? []));
+    const [executingToolCallIds, setExecutingToolCallIds] = useState(() => new Set());
+    const [error, setError] = useState(undefined);
+    const messagesRef = useRef(messages);
+    useEffect(() => {
+        messagesRef.current = messages;
+    }, [messages]);
+    const streamingMessageRef = useRef(null);
+    useEffect(() => {
+        streamingMessageRef.current = streamingMessage;
+    }, [streamingMessage]);
+    const optionsRef = useRef(options);
+    useEffect(() => {
+        optionsRef.current = options;
+    }, [options]);
+    const runIdRef = useRef(0);
+    const abortControllerRef = useRef(null);
+    const failRun = useCallback((err) => {
+        setError(err);
+        optionsRef.current.onError?.(err);
+        setIsStreaming(false);
+    }, []);
+    const runStream = useCallback(async (requestMessages, optimisticUserMessage) => {
+        const opts = optionsRef.current;
+        const myRun = ++runIdRef.current;
+        abortControllerRef.current?.abort();
+        const controller = new AbortController();
+        abortControllerRef.current = controller;
+        const isCurrent = () => runIdRef.current === myRun;
+        setIsStreaming(true);
+        setError(undefined);
+        setPendingDecisions(new Map());
+        setExecutingToolCallIds(new Set());
+        setStreamingMessage(null);
+        if (optimisticUserMessage) {
+            setMessagesState((prev) => [...prev, optimisticUserMessage]);
+        }
+        let skipUserEcho = optimisticUserMessage !== null;
+        const fetchFn = opts.fetch ?? globalThis.fetch;
+        const extraBody = opts.body?.() ?? {};
+        let response;
+        try {
+            response = await fetchFn(opts.api, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ messages: requestMessages, ...extraBody }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (!isCurrent())
+                return;
+            if (controller.signal.aborted) {
+                if (isCurrent())
+                    setIsStreaming(false);
+                return;
+            }
+            failRun(err);
+            return;
+        }
+        if (!isCurrent())
+            return;
+        if (!response.ok) {
+            failRun(new Error(`HTTP ${response.status}: ${response.statusText}`));
+            return;
+        }
+        if (!response.body) {
+            failRun(new Error('Response has no body'));
+            return;
+        }
+        try {
+            for await (const event of parseSSEStream(response.body)) {
+                if (!isCurrent())
+                    return;
+                switch (event.type) {
+                    case 'message_start': {
+                        if (skipUserEcho && event.message.role === 'user') {
+                            skipUserEcho = false;
+                            break;
+                        }
+                        if (event.message.role === 'assistant') {
+                            setStreamingMessage(event.message);
+                        }
+                        break;
+                    }
+                    case 'message_update': {
+                        setStreamingMessage(event.message);
+                        break;
+                    }
+                    case 'message_end': {
+                        if (event.message.role === 'assistant') {
+                            setStreamingMessage(null);
+                            setMessagesState((prev) => [...prev, event.message]);
+                        }
+                        else if (event.message.role === 'toolResult') {
+                            setMessagesState((prev) => [...prev, event.message]);
+                        }
+                        opts.onMessage?.(event.message);
+                        break;
+                    }
+                    case 'tool_execution_start': {
+                        setExecutingToolCallIds((prev) => {
+                            const next = new Set(prev);
+                            next.add(event.toolCallId);
+                            return next;
+                        });
+                        opts.onToolExecutionStart?.({
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                        });
+                        break;
+                    }
+                    case 'tool_execution_end': {
+                        setExecutingToolCallIds((prev) => {
+                            if (!prev.has(event.toolCallId))
+                                return prev;
+                            const next = new Set(prev);
+                            next.delete(event.toolCallId);
+                            return next;
+                        });
+                        opts.onToolExecutionEnd?.({
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            result: event.result,
+                            isError: event.isError,
+                        });
+                        break;
+                    }
+                    case 'tool_decision_pending': {
+                        setPendingDecisions((prev) => {
+                            const next = new Map(prev);
+                            next.set(event.toolCallId, event);
+                            return next;
+                        });
+                        opts.onDecisionPending?.(event);
+                        break;
+                    }
+                    case 'agent_end': {
+                        setStreamingMessage(null);
+                        setMessagesState(() => {
+                            if (!isCurrent())
+                                return messagesRef.current;
+                            return event.messages;
+                        });
+                        const lastAssistant = [...event.messages]
+                            .reverse()
+                            .find((m) => m.role === 'assistant');
+                        if (lastAssistant) {
+                            opts.onFinish?.(lastAssistant);
+                        }
+                        break;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (!isCurrent())
+                return;
+            if (controller.signal.aborted)
+                return;
+            failRun(err);
+            return;
+        }
+        finally {
+            if (isCurrent()) {
+                setIsStreaming(false);
+                abortControllerRef.current = null;
+            }
+        }
+    }, [failRun]);
+    const sendMessages = useCallback(async (msgs) => {
+        setMessagesState(msgs);
+        messagesRef.current = msgs;
+        await runStream(msgs, null);
+    }, [runStream]);
+    const send = useCallback(async (input) => {
+        const userMessage = typeof input === 'string' ? createUserMessage(input) : input;
+        const requestMessages = [...messagesRef.current, userMessage];
+        messagesRef.current = requestMessages;
+        await runStream(requestMessages, userMessage);
+    }, [runStream]);
+    const respondWithDecision = useCallback(async (toolCallId, value) => {
+        const current = messagesRef.current;
+        let targetIdx = -1;
+        for (let i = current.length - 1; i >= 0; i--) {
+            const msg = current[i];
+            if (msg.role !== 'assistant')
+                continue;
+            const match = msg.content.find((block) => block.type === 'toolCall' && block.id === toolCallId);
+            if (!match)
+                continue;
+            if ('decision' in match && match.decision !== undefined)
+                continue;
+            targetIdx = i;
+            break;
+        }
+        if (targetIdx === -1) {
+            throw new Error(`No pending decision for toolCallId '${toolCallId}'`);
+        }
+        const target = current[targetIdx];
+        const updatedAssistant = {
+            ...target,
+            content: target.content.map((block) => {
+                if (block.type !== 'toolCall' || block.id !== toolCallId) {
+                    return block;
+                }
+                return { ...block, decision: value };
+            }),
+        };
+        const requestMessages = [
+            ...current.slice(0, targetIdx),
+            updatedAssistant,
+            ...current.slice(targetIdx + 1),
+        ];
+        setMessagesState(requestMessages);
+        messagesRef.current = requestMessages;
+        setPendingDecisions((prev) => {
+            if (!prev.has(toolCallId))
+                return prev;
+            const next = new Map(prev);
+            next.delete(toolCallId);
+            return next;
+        });
+        await runStream(requestMessages, null);
+    }, [runStream]);
+    const setMessages = useCallback((update) => {
+        setMessagesState((prev) => {
+            const next = typeof update === 'function' ? update(prev) : update;
+            messagesRef.current = next;
+            setPendingDecisions(rederivePendingDecisions(next));
+            setExecutingToolCallIds(new Set());
+            setError(undefined);
+            return next;
+        });
+    }, []);
+    useEffect(() => {
+        return () => {
+            abortControllerRef.current?.abort();
+            abortControllerRef.current = null;
+        };
+    }, []);
+    const abort = useCallback(() => {
+        abortControllerRef.current?.abort();
+        abortControllerRef.current = null;
+        runIdRef.current++;
+        // Snapshot the in-flight assistant message before clearing so visible text
+        // survives the stop. Drop toolCall blocks — without results they'd surface
+        // as pending decisions via rederivePendingDecisions and re-pause the agent.
+        const partial = streamingMessageRef.current;
+        if (partial) {
+            const visible = partial.content.filter((b) => b.type === 'text' && b.text.length > 0);
+            if (visible.length > 0) {
+                setMessagesState((prev) => [...prev, { ...partial, content: visible }]);
+            }
+        }
+        setIsStreaming(false);
+        setStreamingMessage(null);
+        setExecutingToolCallIds(new Set());
+        setPendingDecisions(new Map());
+    }, []);
+    return useMemo(() => ({
+        messages,
+        streamingMessage,
+        isStreaming,
+        pendingDecisions,
+        executingToolCallIds,
+        error,
+        send,
+        sendMessages,
+        setMessages,
+        respondWithDecision,
+        abort,
+    }), [
+        messages,
+        streamingMessage,
+        isStreaming,
+        pendingDecisions,
+        executingToolCallIds,
+        error,
+        send,
+        sendMessages,
+        setMessages,
+        respondWithDecision,
+        abort,
+    ]);
+}

package/index.d.ts

@@ -0,0 +1 @@
+export { type ToolDecisionPendingEvent, useChat, type UseChatOptions, type UseChatResult, } from './use-chat.js';

package/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useChat = void 0;
+var use_chat_js_1 = require("./use-chat.js");
+Object.defineProperty(exports, "useChat", { enumerable: true, get: function () { return use_chat_js_1.useChat; } });

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@agentic-kit/react",
+  "version": "0.2.0",
+  "author": "Dan Lynch <pyramation@gmail.com>",
+  "description": "React bindings for agentic-kit (useChat hook)",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./esm/index.js",
+      "require": "./index.js"
+    }
+  },
+  "homepage": "https://github.com/constructive-io/agentic-kit",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/agentic-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/agentic-kit/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "postbuild": "node ../../scripts/write-esm-package-json.js",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@agentic-kit/agent": "0.3.0",
+    "agentic-kit": "1.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/react": "16.3.2",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "19.2.5",
+    "react-dom": "19.2.5"
+  },
+  "keywords": [],
+  "gitHead": "d4f3f660be621267efe12671c22db202ccdb3f0b"
+}

package/use-chat.d.ts

@@ -0,0 +1,42 @@
+import type { AgentEvent, AgentToolResult } from '@agentic-kit/agent';
+import type { AssistantMessage, Message } from 'agentic-kit';
+export type ToolDecisionPendingEvent = Extract<AgentEvent, {
+    type: 'tool_decision_pending';
+}>;
+export interface ToolExecutionStartEvent {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export interface ToolExecutionEndEvent {
+    toolCallId: string;
+    toolName: string;
+    result: AgentToolResult;
+    isError: boolean;
+}
+export interface UseChatOptions {
+    api: string;
+    body?: () => Record<string, unknown>;
+    initialMessages?: Message[];
+    fetch?: typeof globalThis.fetch;
+    onMessage?: (message: Message) => void;
+    onFinish?: (message: AssistantMessage) => void;
+    onDecisionPending?: (event: ToolDecisionPendingEvent) => void;
+    onToolExecutionStart?: (event: ToolExecutionStartEvent) => void;
+    onToolExecutionEnd?: (event: ToolExecutionEndEvent) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseChatResult {
+    messages: Message[];
+    streamingMessage: AssistantMessage | null;
+    isStreaming: boolean;
+    pendingDecisions: ReadonlyMap<string, ToolDecisionPendingEvent>;
+    executingToolCallIds: ReadonlySet<string>;
+    error: unknown;
+    send: (input: string | Message) => Promise<void>;
+    sendMessages: (messages: Message[]) => Promise<void>;
+    setMessages: (msgs: Message[] | ((prev: Message[]) => Message[])) => void;
+    respondWithDecision: (toolCallId: string, value: unknown) => Promise<void>;
+    abort: () => void;
+}
+export declare function useChat(options: UseChatOptions): UseChatResult;

package/use-chat.js

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useChat = useChat;
+const agent_1 = require("@agentic-kit/agent");
+const agentic_kit_1 = require("agentic-kit");
+const react_1 = require("react");
+/**
+ * Compute the pendingDecisions map from a messages array. A toolCall counts as
+ * pending when it has neither a `decision` field nor a paired `toolResult`.
+ *
+ * Used on `setMessages` to recompute server-derived state from the new array.
+ * The synthesized event is a stub (no `input`, no `schema`) — the original
+ * decision-pending event is not recoverable from messages alone, but the map
+ * key (toolCallId) is what consumers actually need to render decision UI.
+ */
+function rederivePendingDecisions(messages) {
+    const completed = new Set();
+    for (const m of messages) {
+        if (m.role === 'toolResult')
+            completed.add(m.toolCallId);
+    }
+    const pending = new Map();
+    for (const m of messages) {
+        if (m.role !== 'assistant')
+            continue;
+        for (const block of m.content) {
+            if (block.type !== 'toolCall')
+                continue;
+            if (completed.has(block.id))
+                continue;
+            if ('decision' in block && block.decision !== undefined)
+                continue;
+            pending.set(block.id, {
+                type: 'tool_decision_pending',
+                toolCallId: block.id,
+                toolName: block.name,
+                input: block.arguments,
+                schema: { type: 'object' },
+            });
+        }
+    }
+    return pending;
+}
+function useChat(options) {
+    const [messages, setMessagesState] = (0, react_1.useState)(() => options.initialMessages ?? []);
+    const [streamingMessage, setStreamingMessage] = (0, react_1.useState)(null);
+    const [isStreaming, setIsStreaming] = (0, react_1.useState)(false);
+    const [pendingDecisions, setPendingDecisions] = (0, react_1.useState)(() => rederivePendingDecisions(options.initialMessages ?? []));
+    const [executingToolCallIds, setExecutingToolCallIds] = (0, react_1.useState)(() => new Set());
+    const [error, setError] = (0, react_1.useState)(undefined);
+    const messagesRef = (0, react_1.useRef)(messages);
+    (0, react_1.useEffect)(() => {
+        messagesRef.current = messages;
+    }, [messages]);
+    const streamingMessageRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        streamingMessageRef.current = streamingMessage;
+    }, [streamingMessage]);
+    const optionsRef = (0, react_1.useRef)(options);
+    (0, react_1.useEffect)(() => {
+        optionsRef.current = options;
+    }, [options]);
+    const runIdRef = (0, react_1.useRef)(0);
+    const abortControllerRef = (0, react_1.useRef)(null);
+    const failRun = (0, react_1.useCallback)((err) => {
+        setError(err);
+        optionsRef.current.onError?.(err);
+        setIsStreaming(false);
+    }, []);
+    const runStream = (0, react_1.useCallback)(async (requestMessages, optimisticUserMessage) => {
+        const opts = optionsRef.current;
+        const myRun = ++runIdRef.current;
+        abortControllerRef.current?.abort();
+        const controller = new AbortController();
+        abortControllerRef.current = controller;
+        const isCurrent = () => runIdRef.current === myRun;
+        setIsStreaming(true);
+        setError(undefined);
+        setPendingDecisions(new Map());
+        setExecutingToolCallIds(new Set());
+        setStreamingMessage(null);
+        if (optimisticUserMessage) {
+            setMessagesState((prev) => [...prev, optimisticUserMessage]);
+        }
+        let skipUserEcho = optimisticUserMessage !== null;
+        const fetchFn = opts.fetch ?? globalThis.fetch;
+        const extraBody = opts.body?.() ?? {};
+        let response;
+        try {
+            response = await fetchFn(opts.api, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ messages: requestMessages, ...extraBody }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (!isCurrent())
+                return;
+            if (controller.signal.aborted) {
+                if (isCurrent())
+                    setIsStreaming(false);
+                return;
+            }
+            failRun(err);
+            return;
+        }
+        if (!isCurrent())
+            return;
+        if (!response.ok) {
+            failRun(new Error(`HTTP ${response.status}: ${response.statusText}`));
+            return;
+        }
+        if (!response.body) {
+            failRun(new Error('Response has no body'));
+            return;
+        }
+        try {
+            for await (const event of (0, agent_1.parseSSEStream)(response.body)) {
+                if (!isCurrent())
+                    return;
+                switch (event.type) {
+                    case 'message_start': {
+                        if (skipUserEcho && event.message.role === 'user') {
+                            skipUserEcho = false;
+                            break;
+                        }
+                        if (event.message.role === 'assistant') {
+                            setStreamingMessage(event.message);
+                        }
+                        break;
+                    }
+                    case 'message_update': {
+                        setStreamingMessage(event.message);
+                        break;
+                    }
+                    case 'message_end': {
+                        if (event.message.role === 'assistant') {
+                            setStreamingMessage(null);
+                            setMessagesState((prev) => [...prev, event.message]);
+                        }
+                        else if (event.message.role === 'toolResult') {
+                            setMessagesState((prev) => [...prev, event.message]);
+                        }
+                        opts.onMessage?.(event.message);
+                        break;
+                    }
+                    case 'tool_execution_start': {
+                        setExecutingToolCallIds((prev) => {
+                            const next = new Set(prev);
+                            next.add(event.toolCallId);
+                            return next;
+                        });
+                        opts.onToolExecutionStart?.({
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                        });
+                        break;
+                    }
+                    case 'tool_execution_end': {
+                        setExecutingToolCallIds((prev) => {
+                            if (!prev.has(event.toolCallId))
+                                return prev;
+                            const next = new Set(prev);
+                            next.delete(event.toolCallId);
+                            return next;
+                        });
+                        opts.onToolExecutionEnd?.({
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            result: event.result,
+                            isError: event.isError,
+                        });
+                        break;
+                    }
+                    case 'tool_decision_pending': {
+                        setPendingDecisions((prev) => {
+                            const next = new Map(prev);
+                            next.set(event.toolCallId, event);
+                            return next;
+                        });
+                        opts.onDecisionPending?.(event);
+                        break;
+                    }
+                    case 'agent_end': {
+                        setStreamingMessage(null);
+                        setMessagesState(() => {
+                            if (!isCurrent())
+                                return messagesRef.current;
+                            return event.messages;
+                        });
+                        const lastAssistant = [...event.messages]
+                            .reverse()
+                            .find((m) => m.role === 'assistant');
+                        if (lastAssistant) {
+                            opts.onFinish?.(lastAssistant);
+                        }
+                        break;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (!isCurrent())
+                return;
+            if (controller.signal.aborted)
+                return;
+            failRun(err);
+            return;
+        }
+        finally {
+            if (isCurrent()) {
+                setIsStreaming(false);
+                abortControllerRef.current = null;
+            }
+        }
+    }, [failRun]);
+    const sendMessages = (0, react_1.useCallback)(async (msgs) => {
+        setMessagesState(msgs);
+        messagesRef.current = msgs;
+        await runStream(msgs, null);
+    }, [runStream]);
+    const send = (0, react_1.useCallback)(async (input) => {
+        const userMessage = typeof input === 'string' ? (0, agentic_kit_1.createUserMessage)(input) : input;
+        const requestMessages = [...messagesRef.current, userMessage];
+        messagesRef.current = requestMessages;
+        await runStream(requestMessages, userMessage);
+    }, [runStream]);
+    const respondWithDecision = (0, react_1.useCallback)(async (toolCallId, value) => {
+        const current = messagesRef.current;
+        let targetIdx = -1;
+        for (let i = current.length - 1; i >= 0; i--) {
+            const msg = current[i];
+            if (msg.role !== 'assistant')
+                continue;
+            const match = msg.content.find((block) => block.type === 'toolCall' && block.id === toolCallId);
+            if (!match)
+                continue;
+            if ('decision' in match && match.decision !== undefined)
+                continue;
+            targetIdx = i;
+            break;
+        }
+        if (targetIdx === -1) {
+            throw new Error(`No pending decision for toolCallId '${toolCallId}'`);
+        }
+        const target = current[targetIdx];
+        const updatedAssistant = {
+            ...target,
+            content: target.content.map((block) => {
+                if (block.type !== 'toolCall' || block.id !== toolCallId) {
+                    return block;
+                }
+                return { ...block, decision: value };
+            }),
+        };
+        const requestMessages = [
+            ...current.slice(0, targetIdx),
+            updatedAssistant,
+            ...current.slice(targetIdx + 1),
+        ];
+        setMessagesState(requestMessages);
+        messagesRef.current = requestMessages;
+        setPendingDecisions((prev) => {
+            if (!prev.has(toolCallId))
+                return prev;
+            const next = new Map(prev);
+            next.delete(toolCallId);
+            return next;
+        });
+        await runStream(requestMessages, null);
+    }, [runStream]);
+    const setMessages = (0, react_1.useCallback)((update) => {
+        setMessagesState((prev) => {
+            const next = typeof update === 'function' ? update(prev) : update;
+            messagesRef.current = next;
+            setPendingDecisions(rederivePendingDecisions(next));
+            setExecutingToolCallIds(new Set());
+            setError(undefined);
+            return next;
+        });
+    }, []);
+    (0, react_1.useEffect)(() => {
+        return () => {
+            abortControllerRef.current?.abort();
+            abortControllerRef.current = null;
+        };
+    }, []);
+    const abort = (0, react_1.useCallback)(() => {
+        abortControllerRef.current?.abort();
+        abortControllerRef.current = null;
+        runIdRef.current++;
+        // Snapshot the in-flight assistant message before clearing so visible text
+        // survives the stop. Drop toolCall blocks — without results they'd surface
+        // as pending decisions via rederivePendingDecisions and re-pause the agent.
+        const partial = streamingMessageRef.current;
+        if (partial) {
+            const visible = partial.content.filter((b) => b.type === 'text' && b.text.length > 0);
+            if (visible.length > 0) {
+                setMessagesState((prev) => [...prev, { ...partial, content: visible }]);
+            }
+        }
+        setIsStreaming(false);
+        setStreamingMessage(null);
+        setExecutingToolCallIds(new Set());
+        setPendingDecisions(new Map());
+    }, []);
+    return (0, react_1.useMemo)(() => ({
+        messages,
+        streamingMessage,
+        isStreaming,
+        pendingDecisions,
+        executingToolCallIds,
+        error,
+        send,
+        sendMessages,
+        setMessages,
+        respondWithDecision,
+        abort,
+    }), [
+        messages,
+        streamingMessage,
+        isStreaming,
+        pendingDecisions,
+        executingToolCallIds,
+        error,
+        send,
+        sendMessages,
+        setMessages,
+        respondWithDecision,
+        abort,
+    ]);
+}