@ciridae/ui 0.16.1 → 1.0.1

package/dist/chat/mock-chat-client.js

@@ -0,0 +1,566 @@
+import { ChatApiError } from "./chat-api-error.js";
+import { AnswerQuestionRequestSchema, ApprovalSchema, AttachmentSchema, ConversationSchema, CreatedItemSchema, ItemSchema, parseMentions, ResponseSchema, } from "./contract.js";
+const defaultStepDelayMs = 900;
+const defaultToolDurationMs = 1600;
+const defaultNetworkDelayMs = 120;
+const defaultFirstItemsReadDelayMs = 1500;
+const defaultUploadDelayMs = 700;
+/** How long a new response waits in the queue before the agent starts it. */
+const queuedDelayMs = 400;
+const conversationPageSize = 20;
+const seededStepSpacingMs = 4000;
+let mockClientCount = 0;
+/**
+ * An in-memory chat service with a scripted agent, for the showcase and for tests. Seeded turns
+ * exist from the start; `liveSteps` and new messages play out on timers, so polling sees the
+ * same progression a real service would produce.
+ */
+export function createMockChatClient({ conversations: conversationSeeds = [], respond = respondWithDefaultScript, respondToSteering = respondToSteeringWithDefaultScript, stepDelayMs = defaultStepDelayMs, networkDelayMs = defaultNetworkDelayMs, firstItemsReadDelayMs = defaultFirstItemsReadDelayMs, uploadDelayMs = defaultUploadDelayMs, cacheKey = `mock-${++mockClientCount}`, } = {}) {
+    let nextIdentifier = 1;
+    const conversations = new Map();
+    const runs = new Map();
+    const responses = new Map();
+    const uploadedAttachments = new Map();
+    const conversationIdsWithItemsRead = new Set();
+    for (const seed of conversationSeeds)
+        seedConversation(seed);
+    function createIdentifier(prefix) {
+        return `${prefix}_${nextIdentifier++}`;
+    }
+    function seedConversation(seed) {
+        const updatedAt = new Date(Date.now() - (seed.updatedMinutesAgo ?? 0) * 60000);
+        const conversation = createConversationRecord({
+            id: seed.id,
+            agent: seed.agent,
+            title: seed.title,
+            createdAt: new Date(updatedAt.getTime() - seed.turns.length * 10 * seededStepSpacingMs),
+        });
+        conversation.updatedAt = updatedAt;
+        seed.turns.forEach((turn, index) => {
+            const isLastTurn = index === seed.turns.length - 1;
+            const startedAt = new Date(turn.startedSecondsAgo === undefined
+                ? updatedAt.getTime() - (seed.turns.length - index) * 10 * seededStepSpacingMs
+                : Date.now() - turn.startedSecondsAgo * 1000);
+            const response = createResponseRecord(conversation, startedAt);
+            let timestamp = startedAt.getTime();
+            const nextTimestamp = () => new Date((timestamp += seededStepSpacingMs));
+            appendItem(conversation, response.id, startedAt, {
+                type: "message",
+                role: "user",
+                content: turn.message,
+                attachments: (turn.attachments ?? []).map((attachment) => ({
+                    id: createIdentifier("file"),
+                    name: attachment.name,
+                    media_type: attachment.media_type,
+                    size_bytes: attachment.size_bytes,
+                    url: attachment.url ?? null,
+                })),
+            });
+            let failure = null;
+            for (const step of turn.steps) {
+                failure = appendPlayedStep(conversation, response.id, step, nextTimestamp);
+                if (failure)
+                    break;
+            }
+            markUserMessagesRead(conversation);
+            if (isLastTurn && turn.liveSteps) {
+                startRun(conversation, response, [...turn.liveSteps]);
+                return;
+            }
+            settleResponse(response, failure ? "failed" : turn.cancelled ? "cancelled" : "completed", failure, nextTimestamp());
+        });
+    }
+    function createConversationRecord({ id, agent = "assistant", title, createdAt, }) {
+        const conversation = {
+            id: ConversationSchema.shape.id.parse(id ?? createIdentifier("conv")),
+            agent,
+            title,
+            createdAt,
+            updatedAt: createdAt,
+            items: [],
+            nextSeq: 1,
+            latestResponseId: null,
+        };
+        conversations.set(conversation.id, conversation);
+        return conversation;
+    }
+    function createResponseRecord(conversation, createdAt, status = "in_progress") {
+        const response = ResponseSchema.parse({
+            id: createIdentifier("resp"),
+            conversation_id: conversation.id,
+            status,
+            output_item_ids: [],
+            usage: null,
+            error: null,
+            created_at: createdAt.toISOString(),
+            completed_at: null,
+        });
+        responses.set(response.id, response);
+        conversation.latestResponseId = response.id;
+        return response;
+    }
+    function appendItem(conversation, responseId, createdAt, fields) {
+        const item = ItemSchema.parse({
+            ...fields,
+            id: createIdentifier("item"),
+            conversation_id: conversation.id,
+            seq: conversation.nextSeq++,
+            response_id: responseId,
+            created_at: createdAt.toISOString(),
+        });
+        conversation.items.push(item);
+        conversation.updatedAt = createdAt;
+        const response = responses.get(responseId);
+        if (response && !(item.type === "message" && item.role === "user")) {
+            response.output_item_ids.push(item.id);
+        }
+        return item;
+    }
+    /** Appends a step that already happened; returns the failure when the step ends the turn. */
+    function appendPlayedStep(conversation, responseId, step, nextTimestamp) {
+        switch (step.type) {
+            case "reasoning":
+                appendItem(conversation, responseId, nextTimestamp(), {
+                    type: "reasoning",
+                    content: step.content,
+                });
+                return null;
+            case "message":
+                appendItem(conversation, responseId, nextTimestamp(), {
+                    type: "message",
+                    role: "assistant",
+                    content: step.content,
+                    attachments: [],
+                });
+                return null;
+            case "user_message":
+                appendItem(conversation, responseId, nextTimestamp(), {
+                    type: "message",
+                    role: "user",
+                    content: step.content,
+                    attachments: [],
+                });
+                return null;
+            case "tool_call": {
+                const callId = createIdentifier("call");
+                appendItem(conversation, responseId, nextTimestamp(), {
+                    type: "function_call",
+                    call_id: callId,
+                    name: step.name,
+                    arguments: JSON.stringify(step.arguments),
+                });
+                appendItem(conversation, responseId, nextTimestamp(), {
+                    type: "function_call_output",
+                    call_id: callId,
+                    status: step.status ?? "completed",
+                    output: JSON.stringify(step.output),
+                });
+                return null;
+            }
+            case "approval":
+                appendItem(conversation, responseId, nextTimestamp(), {
+                    type: "approval_request",
+                    approval_id: createIdentifier("appr"),
+                    tool: step.tool,
+                    arguments: JSON.stringify(step.arguments),
+                    decision: step.decision ?? "allow",
+                });
+                return null;
+            case "question":
+                appendItem(conversation, responseId, nextTimestamp(), {
+                    type: "question",
+                    question_id: createIdentifier("que"),
+                    questions: [...step.questions],
+                    answers: step.answers ?? step.questions.map((question) => [question.options[0]?.label ?? ""]),
+                });
+                return null;
+            case "fail":
+                return { code: step.code, message: step.message };
+        }
+    }
+    function settleResponse(response, status, failure, completedAt) {
+        response.status = status;
+        response.error = failure;
+        response.completed_at = completedAt.toISOString();
+        response.usage = {
+            input_tokens: 1800 + response.output_item_ids.length * 420,
+            output_tokens: 240,
+        };
+    }
+    function startRun(conversation, response, queue) {
+        const run = {
+            conversation,
+            response,
+            queue,
+            stop: new AbortController(),
+            decideApproval: null,
+            answerQuestion: null,
+        };
+        runs.set(response.id, run);
+        void playRun(run).finally(() => runs.delete(response.id));
+    }
+    async function playRun(run) {
+        const { conversation, response, stop } = run;
+        if (response.status === "queued") {
+            if (!(await wait(queuedDelayMs, stop.signal)))
+                return;
+            response.status = "in_progress";
+        }
+        while (run.queue.length > 0) {
+            const step = run.queue.shift();
+            if (!step)
+                break;
+            if (!(await wait(step.delayMs ?? stepDelayMs, stop.signal)))
+                return;
+            // Each step starts by reading what the user sent since the last one.
+            markUserMessagesRead(conversation, new Date());
+            switch (step.type) {
+                case "reasoning":
+                case "message":
+                case "user_message":
+                    appendPlayedStep(conversation, response.id, step, () => new Date());
+                    break;
+                case "tool_call": {
+                    const callId = createIdentifier("call");
+                    appendItem(conversation, response.id, new Date(), {
+                        type: "function_call",
+                        call_id: callId,
+                        name: step.name,
+                        arguments: JSON.stringify(step.arguments),
+                    });
+                    if (!(await wait(step.durationMs ?? defaultToolDurationMs, stop.signal)))
+                        return;
+                    appendItem(conversation, response.id, new Date(), {
+                        type: "function_call_output",
+                        call_id: callId,
+                        status: step.status ?? "completed",
+                        output: JSON.stringify(step.output),
+                    });
+                    break;
+                }
+                case "approval": {
+                    appendItem(conversation, response.id, new Date(), {
+                        type: "approval_request",
+                        approval_id: createIdentifier("appr"),
+                        tool: step.tool,
+                        arguments: JSON.stringify(step.arguments),
+                        decision: null,
+                    });
+                    response.status = "requires_action";
+                    const decision = await new Promise((resolve) => {
+                        run.decideApproval = resolve;
+                        stop.signal.addEventListener("abort", () => resolve(null), { once: true });
+                    });
+                    run.decideApproval = null;
+                    if (decision === null)
+                        return;
+                    response.status = "in_progress";
+                    // A denied tool ends the scripted plan: the agent only reports that it did not run.
+                    if (decision === "deny") {
+                        run.queue = [
+                            { type: "message", content: `Did not run \`${step.tool}\`.`, delayMs: 400 },
+                        ];
+                    }
+                    break;
+                }
+                case "question": {
+                    appendItem(conversation, response.id, new Date(), {
+                        type: "question",
+                        question_id: createIdentifier("que"),
+                        questions: [...step.questions],
+                        answers: null,
+                    });
+                    response.status = "requires_action";
+                    const answers = await new Promise((resolve) => {
+                        run.answerQuestion = resolve;
+                        stop.signal.addEventListener("abort", () => resolve(null), { once: true });
+                    });
+                    run.answerQuestion = null;
+                    if (answers === null)
+                        return;
+                    response.status = "in_progress";
+                    run.queue.unshift(...(step.reply?.(answers) ?? []));
+                    break;
+                }
+                case "fail":
+                    settleResponse(response, "failed", { code: step.code, message: step.message }, new Date());
+                    return;
+            }
+        }
+        settleResponse(response, "completed", null, new Date());
+    }
+    function findUploadedAttachment(attachmentId) {
+        const attachment = uploadedAttachments.get(attachmentId);
+        if (!attachment) {
+            throw new ChatApiError({
+                method: "POST",
+                path: "/v1/conversations/items",
+                status: 400,
+                responseBody: `Unknown attachment ${attachmentId}`,
+            });
+        }
+        return attachment;
+    }
+    function findConversation(conversationId) {
+        const conversation = conversations.get(conversationId);
+        if (!conversation)
+            throw notFound("GET", `/v1/conversations/${conversationId}`);
+        return conversation;
+    }
+    function findResponse(responseId) {
+        const response = responses.get(responseId);
+        if (!response)
+            throw notFound("GET", `/v1/responses/${responseId}`);
+        return response;
+    }
+    function toConversation(conversation) {
+        const latestResponse = conversation.latestResponseId
+            ? responses.get(conversation.latestResponseId)
+            : undefined;
+        return ConversationSchema.parse({
+            id: conversation.id,
+            agent: conversation.agent,
+            title: conversation.title,
+            preview: summarizeLatestMessage(conversation.items),
+            metadata: {},
+            latest_response: latestResponse ?? null,
+            created_at: conversation.createdAt.toISOString(),
+            updated_at: conversation.updatedAt.toISOString(),
+        });
+    }
+    const settle = () => wait(networkDelayMs, new AbortController().signal);
+    return {
+        cacheKey,
+        async createConversation({ agent } = {}) {
+            await settle();
+            const conversation = createConversationRecord({ agent, title: null, createdAt: new Date() });
+            conversationIdsWithItemsRead.add(conversation.id);
+            return toConversation(conversation);
+        },
+        async listConversations({ cursor } = {}) {
+            await settle();
+            const offset = cursor ? Number(cursor) : 0;
+            const ordered = [...conversations.values()].sort((first, second) => second.updatedAt.getTime() - first.updatedAt.getTime());
+            const page = ordered.slice(offset, offset + conversationPageSize);
+            const nextOffset = offset + conversationPageSize;
+            return {
+                data: page.map(toConversation),
+                next_cursor: nextOffset < ordered.length ? String(nextOffset) : null,
+            };
+        },
+        async getConversation(conversationId) {
+            await settle();
+            return toConversation(findConversation(conversationId));
+        },
+        async deleteConversation(conversationId) {
+            await settle();
+            const conversation = findConversation(conversationId);
+            if (conversation.latestResponseId)
+                runs.get(conversation.latestResponseId)?.stop.abort();
+            conversations.delete(conversationId);
+        },
+        async uploadAttachment(file) {
+            await wait(uploadDelayMs, new AbortController().signal);
+            const attachment = AttachmentSchema.parse({
+                id: createIdentifier("file"),
+                name: file.name,
+                media_type: file.type || "application/octet-stream",
+                size_bytes: file.size,
+                url: URL.createObjectURL(file),
+            });
+            uploadedAttachments.set(attachment.id, attachment);
+            return attachment;
+        },
+        getAttachmentUrl: ({ url }) => url,
+        async createItem(conversationId, { content, attachment_ids = [] }) {
+            await settle();
+            const conversation = findConversation(conversationId);
+            const attachments = attachment_ids.map(findUploadedAttachment);
+            const activeRun = conversation.latestResponseId
+                ? runs.get(conversation.latestResponseId)
+                : undefined;
+            const response = activeRun?.response ?? createResponseRecord(conversation, new Date(), "queued");
+            const userMessage = appendItem(conversation, response.id, new Date(), {
+                type: "message",
+                role: "user",
+                content,
+                attachments,
+            });
+            conversation.title ?? (conversation.title = summarizeAsTitle(content));
+            if (activeRun) {
+                activeRun.queue.unshift(...respondToSteering({ content }));
+            }
+            else {
+                startRun(conversation, response, [
+                    ...respond({
+                        content,
+                        attachments: userMessage.type === "message" ? userMessage.attachments : [],
+                    }),
+                ]);
+            }
+            return CreatedItemSchema.parse({ response_id: response.id });
+        },
+        async listItems(conversationId, { after } = {}) {
+            const delayMs = conversationIdsWithItemsRead.has(conversationId)
+                ? networkDelayMs
+                : firstItemsReadDelayMs;
+            await wait(delayMs, new AbortController().signal);
+            conversationIdsWithItemsRead.add(conversationId);
+            const conversation = findConversation(conversationId);
+            return {
+                data: conversation.items
+                    .filter((item) => after === undefined || item.seq > after)
+                    .map((item) => ItemSchema.parse(item)),
+                has_more: false,
+            };
+        },
+        async getResponse(responseId) {
+            await settle();
+            return ResponseSchema.parse(findResponse(responseId));
+        },
+        async cancelResponse(responseId) {
+            await settle();
+            const response = findResponse(responseId);
+            const run = runs.get(responseId);
+            if (run) {
+                run.stop.abort();
+                settleResponse(response, "cancelled", null, new Date());
+            }
+            return ResponseSchema.parse(response);
+        },
+        async decideApproval(responseId, approvalId, decision) {
+            await settle();
+            const response = findResponse(responseId);
+            const conversation = findConversation(response.conversation_id);
+            const request = conversation.items.find((item) => item.type === "approval_request" && item.approval_id === approvalId);
+            if (request?.type !== "approval_request") {
+                throw notFound("POST", `/v1/responses/${responseId}/approvals/${approvalId}`);
+            }
+            request.decision = decision;
+            runs.get(responseId)?.decideApproval?.(decision);
+            return ApprovalSchema.parse({
+                id: approvalId,
+                response_id: responseId,
+                item_id: request.id,
+                tool: request.tool,
+                arguments: request.arguments,
+                decision,
+                decided_by: "mock-user",
+                decided_at: new Date().toISOString(),
+            });
+        },
+        async answerQuestion(conversationId, questionId, answers) {
+            await settle();
+            const path = `/v1/conversations/${conversationId}/questions/${questionId}/answer`;
+            const request = AnswerQuestionRequestSchema.parse({ answers });
+            const question = findConversation(conversationId).items.find((item) => item.type === "question" && item.question_id === questionId);
+            if (question?.type !== "question")
+                throw notFound("POST", path);
+            if (question.answers !== null) {
+                throw new ChatApiError({
+                    method: "POST",
+                    path,
+                    status: 409,
+                    responseBody: "Already answered",
+                });
+            }
+            question.answers = request.answers;
+            runs.get(question.response_id)?.answerQuestion?.(request.answers);
+        },
+    };
+}
+/** Resolves true after `durationMs`, or false as soon as `signal` aborts. */
+function wait(durationMs, signal) {
+    if (signal.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(true), durationMs);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve(false);
+        }, { once: true });
+    });
+}
+function notFound(method, path) {
+    return new ChatApiError({ method, path, status: 404, responseBody: "Not found" });
+}
+/** Marks the conversation's unread user messages read: at `readAt`, or a second after each was sent. */
+function markUserMessagesRead(conversation, readAt) {
+    for (const item of conversation.items) {
+        if (item.type !== "message" || item.role !== "user" || item.read_at)
+            continue;
+        item.read_at = (readAt ?? new Date(Date.parse(item.created_at) + 1000)).toISOString();
+    }
+}
+const previewLength = 160;
+/** The latest message as one plain line, as the service previews it in the conversation list. */
+function summarizeLatestMessage(items) {
+    const messages = items.flatMap((item) => (item.type === "message" ? [item] : []));
+    const latestMessage = messages[messages.length - 1];
+    if (!latestMessage)
+        return null;
+    const line = toPlainText(latestMessage.content)
+        .replace(/[*`#|]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    return line.length > previewLength ? `${line.slice(0, previewLength - 3)}...` : line;
+}
+function summarizeAsTitle(content) {
+    const words = toPlainText(content).trim().split(/\s+/).slice(0, 7).join(" ");
+    return words.length > 48 ? `${words.slice(0, 47)}...` : words;
+}
+/** Message text with each mention as its `@label`, as the service writes previews and titles. */
+function toPlainText(content) {
+    return parseMentions(content)
+        .map((part) => (typeof part === "string" ? part : `@${part.label}`))
+        .join("");
+}
+function respondWithDefaultScript({ content }) {
+    const query = toPlainText(content);
+    if (/approv/i.test(content)) {
+        return [
+            { type: "reasoning", content: "This changes data, so it needs approval before it runs." },
+            {
+                type: "approval",
+                tool: "update_invoice_status",
+                arguments: { invoice_id: "INV-2041", status: "paid" },
+            },
+            {
+                type: "tool_call",
+                name: "update_invoice_status",
+                arguments: { invoice_id: "INV-2041", status: "paid" },
+                output: { invoice_id: "INV-2041", status: "paid" },
+            },
+            { type: "message", content: "Marked **INV-2041** as paid." },
+        ];
+    }
+    if (/fail/i.test(content)) {
+        return [
+            { type: "reasoning", content: "Checking the ledger export." },
+            {
+                type: "tool_call",
+                name: "export_ledger",
+                arguments: { period: "2026-09" },
+                output: { error: "Ledger service timed out after 30s" },
+                status: "failed",
+            },
+            { type: "fail", code: "tool_error", message: "The ledger service timed out." },
+        ];
+    }
+    return [
+        { type: "reasoning", content: `Looking for records related to "${query}".` },
+        {
+            type: "tool_call",
+            name: "search_records",
+            arguments: { query, limit: 5 },
+            output: { results: [{ id: "REC-118", title: "Quarterly vendor review" }] },
+        },
+        {
+            type: "message",
+            content: `Found one match for **${content}**:\n\n- REC-118, Quarterly vendor review`,
+        },
+    ];
+}
+function respondToSteeringWithDefaultScript({ content }) {
+    return [{ type: "message", content: `Noted. Adjusting for: ${content}`, delayMs: 600 }];
+}

package/dist/chat/use-chat-conversation.d.ts

@@ -0,0 +1,43 @@
+import { type ApprovalDecision, type ApprovalRequestItem, type Attachment, type Conversation, type ConversationId, type Item, type QuestionItem, type Response } from "./contract.js";
+import type { ChatClient } from "./chat-client.js";
+/** A message the user sent that the conversation's items do not include yet. */
+export type PendingMessage = {
+    type: "pending_message";
+    localId: string;
+    conversationId: ConversationId | null;
+    content: string;
+    /** Already uploaded; the message references them by id. */
+    attachments: readonly Attachment[];
+    /** When the user sent it, as epoch milliseconds, so it groups with the messages around it. */
+    sentAt: number;
+    /** `posted` once the service accepted it, until the conversation's items include it. */
+    state: "sending" | "posted" | "failed";
+};
+export type ChatConversationState = {
+    conversation: Conversation | undefined;
+    items: readonly Item[];
+    pendingMessages: readonly PendingMessage[];
+    /** The response the conversation is running, or the one that ran last. */
+    response: Response | null;
+    isResponseActive: boolean;
+    isLoading: boolean;
+    loadError: Error | null;
+    /** Sends a message. While a response runs, the message joins it instead of starting another. */
+    sendMessage: (content: string, attachments: readonly Attachment[]) => Promise<void>;
+    cancelResponse: () => Promise<void>;
+    decideApproval: (request: ApprovalRequestItem, decision: ApprovalDecision) => Promise<void>;
+    /** Answers a waiting question with one list of picked labels or typed text per question. */
+    answerQuestion: (question: QuestionItem, answers: string[][]) => Promise<void>;
+    discardPendingMessage: (localId: string) => void;
+};
+/**
+ * Loads a conversation and keeps it current: while its response is active, the response and the
+ * items after the newest one already loaded are polled about once a second, and polling stops
+ * once the response settles. With no `conversationId`, the first message creates a conversation
+ * and reports it through `onConversationCreated`.
+ */
+export declare function useChatConversation({ client, conversationId, onConversationCreated, }: {
+    client: ChatClient;
+    conversationId: ConversationId | null;
+    onConversationCreated: (conversation: Conversation) => void;
+}): ChatConversationState;