@ciridae/ui 0.16.1 → 1.0.1

package/dist/chat/contract.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+/*
+ * Wire shapes for the agent service API (apps/agent/README.md). Every response body is parsed
+ * through these schemas once, in the client, and the parsed types are the only ones the UI uses.
+ * Field names stay snake_case to match the API.
+ */
+export const ConversationIdSchema = z.string().min(1).brand();
+export const ItemIdSchema = z.string().min(1).brand();
+export const ResponseIdSchema = z.string().min(1).brand();
+export const ApprovalIdSchema = z.string().min(1).brand();
+export const AttachmentIdSchema = z.string().min(1).brand();
+export const QuestionIdSchema = z.string().min(1).brand();
+const TimestampSchema = z.iso.datetime({ offset: true });
+export const ResponseStatusSchema = z.enum([
+    "queued",
+    "in_progress",
+    "requires_action",
+    "completed",
+    "failed",
+    "cancelled",
+]);
+/** Statuses after which a response never changes again. */
+export const settledResponseStatuses = [
+    "completed",
+    "failed",
+    "cancelled",
+];
+export function isResponseActive(status) {
+    return !settledResponseStatuses.includes(status);
+}
+export const ResponseErrorSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+});
+export const ResponseUsageSchema = z.object({
+    input_tokens: z.number().int().nonnegative(),
+    output_tokens: z.number().int().nonnegative(),
+});
+export const ResponseSchema = z.object({
+    id: ResponseIdSchema,
+    conversation_id: ConversationIdSchema,
+    status: ResponseStatusSchema,
+    output_item_ids: z.array(ItemIdSchema),
+    usage: ResponseUsageSchema.nullable(),
+    error: ResponseErrorSchema.nullable(),
+    created_at: TimestampSchema,
+    completed_at: TimestampSchema.nullable(),
+});
+export const ConversationSchema = z.object({
+    id: ConversationIdSchema,
+    agent: z.string(),
+    title: z.string().nullable(),
+    /**
+     * The latest message's text, from the user or the assistant, as one plain line the service
+     * shortens for a conversation list; null before the first message. Optional until every chat
+     * service returns it.
+     */
+    preview: z.string().nullish(),
+    metadata: z.record(z.string(), z.string()),
+    /** The most recent response, so a caller can resume polling or show how the last turn ended. */
+    latest_response: ResponseSchema.nullable(),
+    created_at: TimestampSchema,
+    updated_at: TimestampSchema,
+});
+export const ConversationPageSchema = z.object({
+    data: z.array(ConversationSchema),
+    next_cursor: z.string().nullable(),
+});
+export const AttachmentSchema = z.object({
+    id: AttachmentIdSchema,
+    name: z.string(),
+    media_type: z.string(),
+    size_bytes: z.number().int().nonnegative(),
+    /**
+     * Where the file's bytes are served, as a path relative to the API base
+     * (`/v1/attachments/:id/content`), so it goes through the same proxy and auth as every other
+     * call; null when the service keeps no copy.
+     */
+    url: z.string().nullable(),
+});
+const itemBase = {
+    id: ItemIdSchema,
+    conversation_id: ConversationIdSchema,
+    /** Position in the conversation; strictly increasing, and the `after` cursor for polling. */
+    seq: z.number().int().nonnegative(),
+    response_id: ResponseIdSchema,
+    created_at: TimestampSchema,
+};
+export const MessageItemSchema = z.object({
+    ...itemBase,
+    type: z.literal("message"),
+    role: z.enum(["user", "assistant"]),
+    /** Plain text; mentions are inline as `[@label](mention://kind/id)`, see `MentionSchema`. */
+    content: z.string(),
+    attachments: z.array(AttachmentSchema),
+    /**
+     * When the assistant first saw this user message: the start of the model step that read it.
+     * Null until then and always null on assistant messages. Optional until every service sends it.
+     */
+    read_at: TimestampSchema.nullish(),
+});
+export const FunctionCallItemSchema = z.object({
+    ...itemBase,
+    type: z.literal("function_call"),
+    call_id: z.string().min(1),
+    name: z.string().min(1),
+    /** The call's arguments as a JSON document. */
+    arguments: z.string(),
+});
+export const FunctionCallOutputItemSchema = z.object({
+    ...itemBase,
+    type: z.literal("function_call_output"),
+    call_id: z.string().min(1),
+    status: z.enum(["completed", "failed"]),
+    output: z.string(),
+});
+export const ReasoningItemSchema = z.object({
+    ...itemBase,
+    type: z.literal("reasoning"),
+    content: z.string(),
+});
+export const ApprovalDecisionSchema = z.enum(["allow", "deny"]);
+export const ApprovalRequestItemSchema = z.object({
+    ...itemBase,
+    type: z.literal("approval_request"),
+    approval_id: ApprovalIdSchema,
+    tool: z.string().min(1),
+    /** The arguments the tool would run with, as a JSON document. */
+    arguments: z.string(),
+    decision: ApprovalDecisionSchema.nullable(),
+});
+/**
+ * One prompt from opencode's native `question` tool, in its own shape: a short header, the
+ * question, options with a description each, and whether several may be picked. opencode adds a
+ * free-text answer to every question itself.
+ */
+export const QuestionPromptSchema = z.object({
+    question: z.string(),
+    header: z.string(),
+    options: z.array(z.object({ label: z.string(), description: z.string() })),
+    multiple: z.boolean().optional(),
+});
+/**
+ * The assistant asking the user one or more questions through opencode's `question` tool. The
+ * response waits in `requires_action` until they are answered; `answers` holds one list of picked
+ * labels or typed text per question, or null while unanswered.
+ */
+export const QuestionItemSchema = z.object({
+    ...itemBase,
+    type: z.literal("question"),
+    question_id: QuestionIdSchema,
+    questions: z.array(QuestionPromptSchema).min(1),
+    answers: z.array(z.array(z.string())).nullable(),
+});
+export const ItemSchema = z.discriminatedUnion("type", [
+    MessageItemSchema,
+    FunctionCallItemSchema,
+    FunctionCallOutputItemSchema,
+    ReasoningItemSchema,
+    ApprovalRequestItemSchema,
+    QuestionItemSchema,
+]);
+export const ItemPageSchema = z.object({
+    data: z.array(ItemSchema),
+    has_more: z.boolean(),
+});
+export const CreatedItemSchema = z.object({ response_id: ResponseIdSchema });
+export const ApprovalSchema = z.object({
+    id: ApprovalIdSchema,
+    response_id: ResponseIdSchema,
+    item_id: ItemIdSchema,
+    tool: z.string().min(1),
+    arguments: z.string(),
+    decision: ApprovalDecisionSchema.nullable(),
+    decided_by: z.string().nullable(),
+    decided_at: TimestampSchema.nullable(),
+});
+/**
+ * Something a message points at, such as a record, a field or a document. It travels inside the
+ * message text as `[@label](mention://kind/id)`, so the model reads the label and the reference in
+ * place and the UI draws a chip there; `formatMention` and `parseMentions` convert both ways.
+ */
+export const MentionSchema = z.object({
+    id: z.string().min(1),
+    kind: z.string().regex(/^[a-z][a-z0-9_-]*$/),
+    label: z.string().min(1),
+});
+const mentionPattern = /\[@([^\]]+)\]\(mention:\/\/([a-z][a-z0-9_-]*)\/([^)\s]+)\)/g;
+export function formatMention({ id, kind, label }) {
+    return `[@${label.replace(/[[\]]/g, "")}](mention://${kind}/${encodeURIComponent(id)})`;
+}
+/** Message text split into plain runs and mentions, in order. */
+export function parseMentions(content) {
+    const parts = [];
+    let lastIndex = 0;
+    for (const match of content.matchAll(mentionPattern)) {
+        const [token, label = "", kind = "", encodedId = ""] = match;
+        if (match.index > lastIndex)
+            parts.push(content.slice(lastIndex, match.index));
+        parts.push({ label, kind, id: decodeURIComponent(encodedId) });
+        lastIndex = match.index + token.length;
+    }
+    if (lastIndex < content.length)
+        parts.push(content.slice(lastIndex));
+    return parts;
+}
+export const CreateConversationRequestSchema = z.strictObject({
+    agent: z.string().min(1).optional(),
+    metadata: z.record(z.string(), z.string()).optional(),
+});
+/** Files are uploaded first with `POST /v1/attachments` (multipart, field `file`). */
+export const CreateItemRequestSchema = z.strictObject({
+    content: z.string(),
+    attachment_ids: z.array(AttachmentIdSchema).readonly().optional(),
+});
+export const DecideApprovalRequestSchema = z.strictObject({ decision: ApprovalDecisionSchema });
+/**
+ * `POST /v1/conversations/:id/questions/:question_id/answer`, passed to opencode's `form.reply`:
+ * one list of picked labels or typed text per question, in order.
+ */
+export const AnswerQuestionRequestSchema = z.strictObject({
+    answers: z.array(z.array(z.string().min(1)).min(1)).min(1),
+});

package/dist/chat/conversation-items-query-options.d.ts

@@ -0,0 +1,382 @@
+import { type QueryClient } from "@tanstack/react-query";
+import type { ChatClient } from "./chat-client.js";
+import type { ConversationId } from "./contract.js";
+/** A conversation's items, shared by the open conversation and the prefetches that warm it. */
+export declare function conversationItemsQueryOptions(queryClient: QueryClient, client: ChatClient, conversationId: ConversationId | null): import("@tanstack/react-query/build/legacy").UseQueryOptions<({
+    type: "message";
+    role: "user" | "assistant";
+    content: string;
+    attachments: {
+        id: string & import("zod/index.cjs").$brand<"AttachmentId">;
+        name: string;
+        media_type: string;
+        size_bytes: number;
+        url: string | null;
+    }[];
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+    read_at?: string | null | undefined;
+} | {
+    type: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+} | {
+    type: "function_call_output";
+    call_id: string;
+    status: "completed" | "failed";
+    output: string;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+} | {
+    type: "reasoning";
+    content: string;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+} | {
+    type: "approval_request";
+    approval_id: string & import("zod/index.cjs").$brand<"ApprovalId">;
+    tool: string;
+    arguments: string;
+    decision: "allow" | "deny" | null;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+} | {
+    type: "question";
+    question_id: string & import("zod/index.cjs").$brand<"QuestionId">;
+    questions: {
+        question: string;
+        header: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        multiple?: boolean | undefined;
+    }[];
+    answers: string[][] | null;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+})[], Error, ({
+    type: "message";
+    role: "user" | "assistant";
+    content: string;
+    attachments: {
+        id: string & import("zod/index.cjs").$brand<"AttachmentId">;
+        name: string;
+        media_type: string;
+        size_bytes: number;
+        url: string | null;
+    }[];
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+    read_at?: string | null | undefined;
+} | {
+    type: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+} | {
+    type: "function_call_output";
+    call_id: string;
+    status: "completed" | "failed";
+    output: string;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+} | {
+    type: "reasoning";
+    content: string;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+} | {
+    type: "approval_request";
+    approval_id: string & import("zod/index.cjs").$brand<"ApprovalId">;
+    tool: string;
+    arguments: string;
+    decision: "allow" | "deny" | null;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+} | {
+    type: "question";
+    question_id: string & import("zod/index.cjs").$brand<"QuestionId">;
+    questions: {
+        question: string;
+        header: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        multiple?: boolean | undefined;
+    }[];
+    answers: string[][] | null;
+    id: string & import("zod/index.cjs").$brand<"ItemId">;
+    conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+    seq: number;
+    response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+    created_at: string;
+})[], readonly ["ciridae-chat", string, "conversation-items", (string & import("zod/index.cjs").$brand<"ConversationId">) | null]> & {
+    initialData?: ({
+        type: "message";
+        role: "user" | "assistant";
+        content: string;
+        attachments: {
+            id: string & import("zod/index.cjs").$brand<"AttachmentId">;
+            name: string;
+            media_type: string;
+            size_bytes: number;
+            url: string | null;
+        }[];
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+        read_at?: string | null | undefined;
+    } | {
+        type: "function_call";
+        call_id: string;
+        name: string;
+        arguments: string;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    } | {
+        type: "function_call_output";
+        call_id: string;
+        status: "completed" | "failed";
+        output: string;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    } | {
+        type: "reasoning";
+        content: string;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    } | {
+        type: "approval_request";
+        approval_id: string & import("zod/index.cjs").$brand<"ApprovalId">;
+        tool: string;
+        arguments: string;
+        decision: "allow" | "deny" | null;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    } | {
+        type: "question";
+        question_id: string & import("zod/index.cjs").$brand<"QuestionId">;
+        questions: {
+            question: string;
+            header: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            multiple?: boolean | undefined;
+        }[];
+        answers: string[][] | null;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    })[] | import("@tanstack/react-query/build/legacy").InitialDataFunction<({
+        type: "message";
+        role: "user" | "assistant";
+        content: string;
+        attachments: {
+            id: string & import("zod/index.cjs").$brand<"AttachmentId">;
+            name: string;
+            media_type: string;
+            size_bytes: number;
+            url: string | null;
+        }[];
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+        read_at?: string | null | undefined;
+    } | {
+        type: "function_call";
+        call_id: string;
+        name: string;
+        arguments: string;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    } | {
+        type: "function_call_output";
+        call_id: string;
+        status: "completed" | "failed";
+        output: string;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    } | {
+        type: "reasoning";
+        content: string;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    } | {
+        type: "approval_request";
+        approval_id: string & import("zod/index.cjs").$brand<"ApprovalId">;
+        tool: string;
+        arguments: string;
+        decision: "allow" | "deny" | null;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    } | {
+        type: "question";
+        question_id: string & import("zod/index.cjs").$brand<"QuestionId">;
+        questions: {
+            question: string;
+            header: string;
+            options: {
+                label: string;
+                description: string;
+            }[];
+            multiple?: boolean | undefined;
+        }[];
+        answers: string[][] | null;
+        id: string & import("zod/index.cjs").$brand<"ItemId">;
+        conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+        seq: number;
+        response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+        created_at: string;
+    })[]> | undefined;
+} & {
+    queryKey: readonly ["ciridae-chat", string, "conversation-items", (string & import("zod/index.cjs").$brand<"ConversationId">) | null] & {
+        [dataTagSymbol]: ({
+            type: "message";
+            role: "user" | "assistant";
+            content: string;
+            attachments: {
+                id: string & import("zod/index.cjs").$brand<"AttachmentId">;
+                name: string;
+                media_type: string;
+                size_bytes: number;
+                url: string | null;
+            }[];
+            id: string & import("zod/index.cjs").$brand<"ItemId">;
+            conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+            seq: number;
+            response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+            created_at: string;
+            read_at?: string | null | undefined;
+        } | {
+            type: "function_call";
+            call_id: string;
+            name: string;
+            arguments: string;
+            id: string & import("zod/index.cjs").$brand<"ItemId">;
+            conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+            seq: number;
+            response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+            created_at: string;
+        } | {
+            type: "function_call_output";
+            call_id: string;
+            status: "completed" | "failed";
+            output: string;
+            id: string & import("zod/index.cjs").$brand<"ItemId">;
+            conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+            seq: number;
+            response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+            created_at: string;
+        } | {
+            type: "reasoning";
+            content: string;
+            id: string & import("zod/index.cjs").$brand<"ItemId">;
+            conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+            seq: number;
+            response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+            created_at: string;
+        } | {
+            type: "approval_request";
+            approval_id: string & import("zod/index.cjs").$brand<"ApprovalId">;
+            tool: string;
+            arguments: string;
+            decision: "allow" | "deny" | null;
+            id: string & import("zod/index.cjs").$brand<"ItemId">;
+            conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+            seq: number;
+            response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+            created_at: string;
+        } | {
+            type: "question";
+            question_id: string & import("zod/index.cjs").$brand<"QuestionId">;
+            questions: {
+                question: string;
+                header: string;
+                options: {
+                    label: string;
+                    description: string;
+                }[];
+                multiple?: boolean | undefined;
+            }[];
+            answers: string[][] | null;
+            id: string & import("zod/index.cjs").$brand<"ItemId">;
+            conversation_id: string & import("zod/index.cjs").$brand<"ConversationId">;
+            seq: number;
+            response_id: string & import("zod/index.cjs").$brand<"ResponseId">;
+            created_at: string;
+        })[];
+        [dataTagErrorSymbol]: Error;
+    };
+};

package/dist/chat/conversation-items-query-options.js

@@ -0,0 +1,15 @@
+import { queryOptions, skipToken } from "@tanstack/react-query";
+import { chatQueryKeys } from "./chat-query-keys.js";
+import { fetchNewConversationItems } from "./fetch-new-conversation-items.js";
+/** How long a conversation's items stay cached after nothing shows them, so reopening it is instant. */
+const unusedConversationItemsGcTimeMs = 30 * 60000;
+/** A conversation's items, shared by the open conversation and the prefetches that warm it. */
+export function conversationItemsQueryOptions(queryClient, client, conversationId) {
+    return queryOptions({
+        queryKey: chatQueryKeys.conversationItems(client, conversationId),
+        queryFn: conversationId === null
+            ? skipToken
+            : () => fetchNewConversationItems(queryClient, client, conversationId),
+        gcTime: unusedConversationItemsGcTimeMs,
+    });
+}

package/dist/chat/describe-tool-call.d.ts

@@ -0,0 +1,5 @@
+/**
+ * What a tool call waiting for approval asks to do, read from a tool name that starts with its
+ * verb: `search_invoices` is "Search invoices", and a one-word noun like `webfetch` "Use webfetch".
+ */
+export declare function describeApprovalRequest(toolName: string): string;

package/dist/chat/describe-tool-call.js

@@ -0,0 +1,33 @@
+/** Common verbs a tool name can be on its own, so `read` reads as a verb. */
+const singleWordVerbs = new Set([
+    "find",
+    "get",
+    "make",
+    "put",
+    "read",
+    "run",
+    "send",
+    "set",
+    "stop",
+    "write",
+]);
+/**
+ * What a tool call waiting for approval asks to do, read from a tool name that starts with its
+ * verb: `search_invoices` is "Search invoices", and a one-word noun like `webfetch` "Use webfetch".
+ */
+export function describeApprovalRequest(toolName) {
+    const [verb = toolName, ...rest] = splitIdentifierWords(toolName).map((word) => word.toLowerCase());
+    const object = rest.join(" ");
+    if (!object && !singleWordVerbs.has(verb))
+        return `Use ${verb}`;
+    return capitalize([verb, object].filter(Boolean).join(" "));
+}
+function splitIdentifierWords(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[\s_.-]+/)
+        .filter(Boolean);
+}
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}

package/dist/chat/fetch-new-conversation-items.d.ts

@@ -0,0 +1,10 @@
+import type { ChatClient } from "./chat-client.js";
+import type { ConversationId, Item } from "./contract.js";
+import type { QueryClient } from "@tanstack/react-query";
+/**
+ * Fetches the items after the newest cached one, following `has_more`, and returns the cached
+ * items with them merged in seq order. An empty cache fetches the whole conversation. A user
+ * message of the newest response that the assistant has not read yet is fetched again, so its
+ * `read_at` arrives.
+ */
+export declare function fetchNewConversationItems(queryClient: QueryClient, client: ChatClient, conversationId: ConversationId): Promise<Item[]>;