@slices.sh/ai-chat 0.1.0

package/dist/services/ports.d.ts

@@ -0,0 +1,31 @@
+import type { ChatTransport } from "ai";
+import type { AiChatMessage } from "./messages";
+import type { ChatChoices } from "./choices";
+import type { ChatConfig } from "./turn";
+/**
+ * Where a chat's turns go, as the AI SDK's own transport.
+ *
+ * The only thing a screen needs from the installed backend is somewhere to send the
+ * conversation, and the SDK already has the shape for that: a backend with a route answers
+ * with a `DefaultChatTransport` pointed at it. Everything else a screen reads — messages,
+ * status, error, stop, regenerate — comes from the SDK's `Chat` over this transport.
+ */
+export type AiChatClient = {
+    choicesFor?(chat: string, signal?: AbortSignal): Promise<ChatChoices | null>;
+    transportFor(chat: string): ChatTransport<AiChatMessage>;
+};
+export type AiChatServer = {
+    choices?(request: Request, context: {
+        params: Promise<{
+            chat: string;
+        }>;
+    }): Promise<Response>;
+    /** `undefined` for a slug with no entry, which is a 404 and never a fall back to a default. */
+    configFor(chat: string): ChatConfig | undefined;
+    /** Answers with the SDK's UI message stream, or refuses with a status before one starts. */
+    turn(request: Request, context: {
+        params: Promise<{
+            chat: string;
+        }>;
+    }): Promise<Response>;
+};

package/dist/services/questions.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import type { Chat } from "@ai-sdk/react";
+import type { AiChatMessage, AiChatPart } from "./messages";
+export declare const questionSchema: z.ZodObject<{
+    title: z.ZodString;
+    questions: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        choices: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        other: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Questionnaire = z.infer<typeof questionSchema>;
+export type Question = Questionnaire["questions"][number];
+export type QuestionAnswers = Record<string, string | string[]>;
+/** Register as tools.askQuestions. It deliberately has no server execute function. */
+export declare const askQuestions: import("ai").Tool<{
+    title: string;
+    questions: {
+        name: string;
+        title: string;
+        choices: {
+            value: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        multiple?: boolean | undefined;
+        required?: boolean | undefined;
+        other?: string | undefined;
+    }[];
+}, never, import("@ai-sdk/provider-utils").Context>;
+export declare function questionInput(part: AiChatPart): Questionnaire | null;
+export declare function validQuestionAnswer(question: Question, answer: string | string[] | undefined): boolean;
+export type QuestionProblem = "required" | "other";
+/**
+ * Why an answer cannot be sent yet, in the person's terms: an Other they chose and left empty is
+ * a different thing to fix than a question they never answered. Null when it can be sent.
+ */
+export declare function questionProblem(question: Question, answer: string | string[] | undefined, blankOther: boolean): QuestionProblem | null;
+/** What the model reads when the person dismissed the questions instead of answering them. */
+export declare const skippedQuestion: {
+    readonly skipped: true;
+    readonly message: "The user skipped the question.";
+};
+export declare function isSkippedQuestion(part: AiChatPart): boolean;
+export declare function answerQuestions(chat: Chat<AiChatMessage>, toolCallId: string, answers: QuestionAnswers): Promise<void>;
+/**
+ * Resolves the open questions of the last message as skipped, without answering and without
+ * continuing the turn: `shouldContinueChat` ignores them, so whoever skips decides what is sent
+ * next. True when it wrote something.
+ */
+export declare function skipQuestions(chat: Chat<AiChatMessage>, toolCallId?: string): Promise<boolean>;
+/** A message typed while a question is open is the reply to it: the question is skipped first. */
+export declare function sendPastQuestions(chat: Chat<AiChatMessage>, text: string): Promise<void>;
+/**
+ * Only the last message can still be answered (the SDK writes tool outputs there), so a question
+ * left behind a newer message is history and holds nothing back.
+ */
+export declare function awaitingQuestion(messages: AiChatMessage[]): boolean;

package/dist/services/questions.js

@@ -0,0 +1,119 @@
+import { getToolName, isToolUIPart, tool } from "ai";
+import { z } from "zod";
+const choice = z.object({
+  value: z.string().min(1),
+  label: z.string().min(1),
+  description: z.string().optional()
+});
+const question = z.object({
+  name: z.string().regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
+  title: z.string().min(1),
+  description: z.string().optional(),
+  multiple: z.boolean().optional(),
+  required: z.boolean().optional(),
+  choices: z.array(choice).max(9),
+  other: z.string().min(1).optional()
+});
+const questionSchema = z.object({
+  title: z.string().min(1),
+  questions: z.array(question).min(1).max(12)
+});
+const askQuestions = tool({
+  description: "Ask the person questions before continuing. Use unique question names and choice values. Provide choices or an other field. The client returns the person's answers.",
+  inputSchema: questionSchema
+});
+function questionInput(part) {
+  if (!isToolUIPart(part) || getToolName(part) !== "askQuestions") return null;
+  const parsed = questionSchema.safeParse(part.input);
+  if (!parsed.success) return null;
+  const questions = parsed.data.questions;
+  if (new Set(questions.map((q) => q.name)).size !== questions.length || questions.some(
+    (q) => !q.choices.length && !q.other || new Set(q.choices.map((c) => c.value)).size !== q.choices.length
+  ))
+    return null;
+  return parsed.data;
+}
+function validQuestionAnswer(question2, answer) {
+  if (answer !== void 0 && (question2.multiple ? !Array.isArray(answer) : typeof answer !== "string"))
+    return false;
+  const values = (Array.isArray(answer) ? answer : answer ? [answer] : []).filter((value) => value.trim());
+  if (question2.required && !values.length) return false;
+  return values.every(
+    (value) => question2.choices.some((choice2) => choice2.value === value) || Boolean(question2.other)
+  );
+}
+function questionProblem(question2, answer, blankOther) {
+  if (blankOther) return "other";
+  return validQuestionAnswer(question2, answer) ? null : "required";
+}
+const skippedQuestion = { skipped: true, message: "The user skipped the question." };
+function isSkippedQuestion(part) {
+  if (!isToolUIPart(part) || getToolName(part) !== "askQuestions" || part.state !== "output-available")
+    return false;
+  const output = part.output;
+  return typeof output === "object" && output !== null && output.skipped === true;
+}
+const claims = /* @__PURE__ */ new WeakMap();
+function claimed(chat) {
+  let pending = claims.get(chat);
+  if (!pending) {
+    pending = /* @__PURE__ */ new Set();
+    claims.set(chat, pending);
+  }
+  return pending;
+}
+async function answerQuestions(chat, toolCallId, answers) {
+  const pending = claimed(chat);
+  if (pending.has(toolCallId)) return;
+  const part = chat.messages.flatMap((message) => message.parts).find((part2) => isToolUIPart(part2) && part2.toolCallId === toolCallId && part2.state === "input-available");
+  const input = part && questionInput(part);
+  if (!input) return;
+  if (!input.questions.every((q) => validQuestionAnswer(q, answers[q.name])))
+    throw new Error("ai-chat/invalid-answers");
+  const output = Object.fromEntries(
+    input.questions.map((q) => [q.name, answers[q.name] ?? (q.multiple ? [] : "")])
+  );
+  pending.add(toolCallId);
+  try {
+    await chat.addToolOutput({ tool: "askQuestions", toolCallId, output });
+  } finally {
+    pending.delete(toolCallId);
+  }
+}
+async function skipQuestions(chat, toolCallId) {
+  const pending = claimed(chat);
+  const ids = (chat.messages.at(-1)?.parts ?? []).flatMap(
+    (part) => isToolUIPart(part) && part.state === "input-available" && questionInput(part) !== null && (toolCallId === void 0 || part.toolCallId === toolCallId) && !pending.has(part.toolCallId) ? [part.toolCallId] : []
+  );
+  for (const id of ids) pending.add(id);
+  try {
+    for (const id of ids)
+      await chat.addToolOutput({ tool: "askQuestions", toolCallId: id, output: skippedQuestion });
+  } finally {
+    for (const id of ids) pending.delete(id);
+  }
+  return ids.length > 0;
+}
+async function sendPastQuestions(chat, text) {
+  await skipQuestions(chat);
+  await chat.sendMessage({ text });
+}
+function awaitingQuestion(messages) {
+  const last = messages.at(-1);
+  return last?.role === "assistant" && last.parts.some(
+    (part) => isToolUIPart(part) && part.state === "input-available" && questionInput(part) !== null
+  );
+}
+export {
+  answerQuestions,
+  askQuestions,
+  awaitingQuestion,
+  isSkippedQuestion,
+  questionInput,
+  questionProblem,
+  questionSchema,
+  sendPastQuestions,
+  skipQuestions,
+  skippedQuestion,
+  validQuestionAnswer
+};

package/dist/services/request.d.ts

@@ -0,0 +1,26 @@
+import "server-only";
+import type { AiChatMessage } from "./messages";
+import type { ChatConfig, ChatRequestContext, ChatTurnEnd } from "./turn";
+/**
+ * The conversation a turn carries, checked by the SDK's own validator.
+ *
+ * The body is what `DefaultChatTransport` posts — `{ id, messages, trigger, messageId }` —
+ * and `messages` is all of it a route reads: a turn is stateless, so the transcript arrives
+ * whole with every request and nothing here keeps it between them.
+ */
+export declare function requestedTurn(request: Request): Promise<{
+    messages: AiChatMessage[];
+    selection: unknown;
+}>;
+export declare function messagesOf(request: Request): Promise<AiChatMessage[]>;
+/** A turn refused before its stream starts: the status the slug decides, and the slug for the screen. */
+export declare function refusal(failure: unknown): Response;
+/**
+ * A failure once the stream is already open, as the text of the SDK's `error` chunk.
+ *
+ * The status went out with the first byte, so the refusal travels inside the stream, in the
+ * same words a refused request would have had. What went wrong in detail stays here: the
+ * SDK's default says "An error occurred." for the same reason.
+ */
+export declare function streamRefusal(failure: unknown): string;
+export declare function ended(config: ChatConfig, end: ChatTurnEnd, context: ChatRequestContext): Promise<void>;

package/dist/services/request.js

@@ -0,0 +1,85 @@
+import "server-only";
+import { APICallError, safeValidateUIMessages } from "ai";
+import { answerMissingConfiguration, missingConfigurationAnswer } from "@slices.sh/core/configuration/server";
+import { ChatError, isChatError, refusalText, statusForChatError } from "./errors.js";
+async function requestedTurn(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    throw new ChatError("ai-chat/invalid-request", "The turn was not JSON.");
+  }
+  const messages = body?.messages;
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new ChatError("ai-chat/invalid-request", "A turn needs at least one message.");
+  }
+  const checked = await safeValidateUIMessages({ messages });
+  if (!checked.success) {
+    throw new ChatError(
+      "ai-chat/invalid-request",
+      "The turn's messages are not a conversation.",
+      checked.error.message
+    );
+  }
+  if (checked.data.some((message) => message.role === "system")) {
+    throw new ChatError(
+      "ai-chat/invalid-request",
+      "A turn's messages are a person's and a model's, never a system prompt."
+    );
+  }
+  return { messages: checked.data, selection: body.selection };
+}
+async function messagesOf(request) {
+  return (await requestedTurn(request)).messages;
+}
+function refusal(failure) {
+  const missing = answerMissingConfiguration(failure, "ai-chat");
+  if (missing) return missing;
+  const error = reportedFailure(failure, "ai-chat/unavailable", "The chat is unavailable.");
+  if (error.detail) console.error(`[ai-chat] ${error.slug}: ${error.detail}`);
+  return new Response(refusalText(error), {
+    status: statusForChatError[error.slug],
+    headers: {
+      "content-type": "application/json",
+      ...error.retryAt ? { "retry-after": new Date(error.retryAt).toUTCString() } : {}
+    }
+  });
+}
+function streamRefusal(failure) {
+  const missing = missingConfigurationAnswer(failure, "ai-chat");
+  if (missing) return JSON.stringify(missing);
+  const error = reportedFailure(failure, "ai-chat/model-unavailable", "The model stopped answering.");
+  console.error(
+    `[ai-chat] ${error.slug}:`,
+    isChatError(failure) ? failure.detail ?? failure.message : failure
+  );
+  return refusalText(error);
+}
+async function ended(config, end, context) {
+  try {
+    await config.onEnd?.(end, context);
+  } catch (failure) {
+    console.error("[ai-chat] onEnd failed", failure);
+  }
+}
+function reportedFailure(failure, slug, message) {
+  if (isChatError(failure)) return failure;
+  if (APICallError.isInstance(failure) && failure.statusCode === 429) {
+    const value = Object.entries(failure.responseHeaders ?? {}).find(([key]) => key.toLowerCase() === "retry-after")?.[1]?.trim();
+    const deadline = value ? /^\d+$/.test(value) ? Date.now() + Number(value) * 1e3 : Date.parse(value) : void 0;
+    return new ChatError(
+      "ai-chat/rate-limited",
+      "The model is receiving too many requests.",
+      void 0,
+      deadline
+    );
+  }
+  return new ChatError(slug, message);
+}
+export {
+  ended,
+  messagesOf,
+  refusal,
+  requestedTurn,
+  streamRefusal
+};

package/dist/services/selection.d.ts

@@ -0,0 +1,10 @@
+import { type ChatSelection } from "./choices";
+import type { ChatConfig } from "./turn";
+/** A browser may choose only declared alternatives and may disable only optional tools. */
+export declare function selectChat(config: ChatConfig, given: unknown): {
+    model: import("./turn").ChatModel;
+    modelId: string | undefined;
+    selection: ChatSelection;
+    activeTools: string[] | undefined;
+    contextWindow: number | null;
+};

package/dist/services/selection.js

@@ -0,0 +1,49 @@
+import { ChatError } from "./errors.js";
+import { choicesOf, contextWindowOf } from "./choices.js";
+const invalid = () => {
+  throw new ChatError(
+    "ai-chat/invalid-request",
+    "That model or tool selection is unavailable."
+  );
+};
+function selectChat(config, given) {
+  if (given !== void 0 && (!given || typeof given !== "object" || Array.isArray(given)))
+    invalid();
+  const value = given ?? {};
+  if (Object.keys(value).some((key) => key !== "model" && key !== "tools"))
+    invalid();
+  if (value.model !== void 0 && (typeof value.model !== "string" || value.model.length > 128))
+    invalid();
+  const modelId = value.model;
+  if (modelId && !Object.hasOwn(config.models ?? {}, modelId)) invalid();
+  const choice = modelId ? config.models[modelId] : void 0;
+  const available = choicesOf(config)?.tools;
+  if (value.tools !== void 0 && (!available || !Array.isArray(value.tools) || value.tools.length > available.length || value.tools.some(
+    (id) => typeof id !== "string" || !available.some((tool) => tool.id === id)
+  ) || new Set(value.tools).size !== value.tools.length))
+    invalid();
+  const selected = value.tools;
+  const optional = selected ?? available?.filter((tool) => tool.defaultEnabled).map((tool) => tool.id);
+  const activeTools = available ? [
+    ...Object.keys(config.tools ?? {}).filter(
+      (id) => !available.some((tool) => tool.id === id)
+    ),
+    ...optional ?? []
+  ] : void 0;
+  const selection = {
+    ...modelId ? { model: modelId } : {},
+    ...optional ? { tools: [...optional] } : {}
+  };
+  return {
+    model: choice?.model ?? config.model,
+    modelId,
+    selection,
+    activeTools,
+    contextWindow: contextWindowOf(
+      choice ? choice.contextWindow : config.contextWindow
+    )
+  };
+}
+export {
+  selectChat
+};

package/dist/services/sources.d.ts

@@ -0,0 +1,11 @@
+import type { AiChatMessage } from "./messages";
+export type ChatSource = {
+    key: string;
+    number: number;
+    title: string;
+    href: string | null;
+    detail: string;
+};
+/** Only web URLs are navigable citations; document references still carry useful provenance. */
+export declare function sourceHref(value: string): string | null;
+export declare function sourcesOf(message: AiChatMessage): ChatSource[];

package/dist/services/sources.js

@@ -0,0 +1,29 @@
+function sourceHref(value) {
+  try {
+    const url = new URL(value);
+    return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+function sourcesOf(message) {
+  const found = /* @__PURE__ */ new Map();
+  for (const part of message.parts) {
+    if (part.type !== "source-url" && part.type !== "source-document") continue;
+    const key = `${part.type}:${part.sourceId}`;
+    const previous = found.get(key);
+    const href = part.type === "source-url" ? sourceHref(part.url) : null;
+    found.set(key, {
+      key,
+      number: previous?.number ?? found.size + 1,
+      title: part.title?.trim() || (part.type === "source-document" ? part.filename ?? part.sourceId : href ?? part.sourceId),
+      href,
+      detail: part.type === "source-document" ? [part.filename, part.mediaType].filter(Boolean).join(" \xB7 ") : href ?? part.url
+    });
+  }
+  return [...found.values()];
+}
+export {
+  sourceHref,
+  sourcesOf
+};

package/dist/services/tools.d.ts

@@ -0,0 +1,11 @@
+import type { ToolSet } from "ai";
+/**
+ * The SDK's own tool set, so a tool is typed where it is written.
+ *
+ * `config.ts` declares tools with `tool({ description, inputSchema, execute })`, and this is
+ * what makes `inputSchema`'s type flow into `execute`'s argument: the contract could not
+ * have said it, because a structural copy of a schema type is a second definition of
+ * something the SDK already owns, and it would be wrong by the next release.
+ * → services/ai-chat/tools.ts in the contract
+ */
+export type ChatToolSet = ToolSet;

package/dist/services/turn.d.ts

@@ -0,0 +1,84 @@
+import type { LanguageModel, LanguageModelCallOptions, UIMessageStreamOnEndCallback } from "ai";
+import type { AiChatMessage } from "./messages";
+import type { ChatModelOption, ChatToolOption, ChatSelection } from "./choices";
+import type { ChatToolSet } from "./tools";
+/**
+ * The model a chat answers with.
+ *
+ * An id is plain text on purpose: a union would have to name every model every provider
+ * offers, and would be wrong about fine-tunes, previews and anything released after this
+ * file. The installed backend turns it into a model with its own provider and credentials.
+ * A model object built elsewhere — a test double, a provider you configured yourself — is
+ * used as it is, which is what the AI SDK's own `model` option accepts.
+ */
+export type ChatModel = string | Exclude<LanguageModel, string>;
+/** Who is asking, as little of them as a chat needs to decide. */
+export type ChatActor = {
+    id: string | null;
+    organizationId?: string | null;
+};
+export type ChatRequestContext = {
+    chat: string;
+    actor: ChatActor;
+    /** `request.signal` carries the client's abort; a long turn has to honour it. */
+    request: Request;
+    /** The whole conversation, as the SDK's transport sent it: a turn keeps nothing between requests. */
+    messages: AiChatMessage[];
+    /** Validated choices for this turn, never the raw browser payload. */
+    selection?: ChatSelection;
+};
+/** A configured value, or one the request decides — a per-tenant system prompt, say. */
+export type FromContext<T> = T | ((context: ChatRequestContext) => T | Promise<T>);
+/**
+ * How hard a model thinks before it answers, in the AI SDK's own levels, so one chat means
+ * the same thing on every provider: OpenAI hears an effort, Anthropic a thinking budget.
+ */
+export type ChatReasoning = LanguageModelCallOptions["reasoning"];
+/** The SDK's own account of a finished turn: every message, the answer, and whether it was stopped. */
+export type ChatTurnEnd = Parameters<UIMessageStreamOnEndCallback<AiChatMessage>>[0];
+export type ChatConfig = {
+    model: ChatModel;
+    /** Explicit alternatives; omitted means the default model cannot be changed. */
+    models?: Readonly<Record<string, ChatModelOption>>;
+    /** Host-declared capacity of the default model; absent remains unknown. */
+    contextWindow?: number;
+    /** Only these configured tools can be disabled by the caller. Other tools stay required. */
+    toolChoices?: readonly ChatToolOption[];
+    system?: FromContext<string>;
+    temperature?: number;
+    /** Thinking counts against it, so a chat that reasons needs room for both. */
+    maxOutputTokens?: number;
+    /**
+     * Asking for a level is also asking to see the thinking. Left unset, a reasoning model
+     * still thinks — the tokens are spent and billed — but in silence, and `Chat.PartReasoning`
+     * has nothing to draw. A model that cannot reason ignores it.
+     */
+    reasoning?: ChatReasoning;
+    /** What this chat may call, typed by the installed backend. → services/ai-chat/tools.ts */
+    tools?: ChatToolSet;
+    /**
+     * How many model calls one turn may take, which is what makes a turn an agent.
+     *
+     * A number rather than the SDK's stop condition: every backend can honour a count, and a
+     * closure written here would be a closure only one of them understands. One, the default,
+     * is a chat; more than one is a loop that calls a tool and reads its output.
+     */
+    maxSteps?: number;
+    /**
+     * Where persistence and metering hang, and why this contract stores nothing.
+     *
+     * It is the SDK's `onEnd`, with who asked beside it, and it fires for stopped turns too —
+     * `isAborted`, and the partial answer as `responseMessage`: an app that saved only
+     * completed turns would lose exactly the answers someone stopped because they were
+     * already enough. What the turn cost is on `responseMessage.metadata.usage`, where the
+     * provider counted it.
+     */
+    onEnd?(end: ChatTurnEnd, context: ChatRequestContext): void | Promise<void>;
+};
+/**
+ * The chats this app has, keyed by the slug that appears in the URL.
+ *
+ * The key is the API: a screen says `name="support"`, the route answers on
+ * `/api/chat/support`, and `config.ts` is where you look. One name, three places.
+ */
+export type ChatConfigMap = Record<string, ChatConfig>;

package/dist/services/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What a chat backend is, whichever model answers.
+ *
+ * The messages, their parts and the stream that carries them are the AI SDK's own
+ * (`UIMessage`, `UIMessageChunk`, `ChatTransport`); what is here is only what the SDK leaves
+ * to an app — the metadata a route writes, the refusals it can answer with, and how a chat
+ * is configured — because this is the one file the layers above may read.
+ */
+export * from "./errors";
+export * from "./messages";
+export * from "./ports";
+export * from "./tools";
+export * from "./turn";
+export * from "./approval";
+export * from "./approval-memory";
+export * from "./questions";
+export * from "./continue";
+export * from "./sources";
+export * from "./media";
+export * from "./branches";
+export * from "./chat-session";
+export * from "./choices";
+export * from "./selection";

package/dist/services/types.js

@@ -0,0 +1,15 @@
+export * from "./errors.js";
+export * from "./messages.js";
+export * from "./ports.js";
+export * from "./tools.js";
+export * from "./turn.js";
+export * from "./approval.js";
+export * from "./approval-memory.js";
+export * from "./questions.js";
+export * from "./continue.js";
+export * from "./sources.js";
+export * from "./media.js";
+export * from "./branches.js";
+export * from "./chat-session.js";
+export * from "./choices.js";
+export * from "./selection.js";