@intelligo-dev/chat 1.0.0-beta.13

package/src/index.ts

@@ -0,0 +1,93 @@
+/**
+ * The chat transport: `createChatHandler(config)` returns `{ POST, DELETE,
+ * GET }` over Web `Request`/`Response` and runs every turn through auth, rate
+ * limit, feature gate, persistence and the execution boundary. The config
+ * takes AI SDK models, tools and stop conditions as they are.
+ */
+
+export { createChatHandler } from "./handler";
+export { truncateTitle } from "./title";
+export type { ChatHandler } from "./handler";
+
+export type {
+  ChatActor,
+  ChatAgentConfig,
+  ChatAttachmentPolicy,
+  ChatGenerationOptions,
+  ChatMessageKey,
+  ChatMessageParams,
+  ChatMessages,
+  ChatModelsConfig,
+  ChatServerConfig,
+  ChatTurn,
+  ChatTurnContext,
+  ChatTurnEvents,
+  PreparedTurn,
+  ProviderOptions,
+  RateLimitDecision,
+  ResolvedAgent,
+  StreamTurn,
+  TurnStream,
+} from "./config";
+
+export { CHAT_ERROR_STATUS, DEFAULT_CHAT_MESSAGES } from "./errors";
+export { parseChatBody } from "./body";
+export type { ChatBody, ParsedChatBody } from "./body";
+
+export { getChatQuotaState, getChatQuotaStates } from "./quota";
+export { lastUserMessage, toUIMessages } from "./messages";
+export { pickUsage, sumStepUsage } from "./usage";
+export type { TokenUsage } from "./usage";
+export {
+  applyConversationWindow,
+  estimateConversationTokens,
+  estimateTokenCount,
+  extractText,
+} from "./windowing";
+export type {
+  ConversationWindow,
+  ConversationWindowOptions,
+} from "./windowing";
+
+export { createArtifactWriter } from "./artifact-writer";
+export type { ArtifactWriter, ArtifactWriterOptions } from "./artifact-writer";
+export { sanitizeForShare } from "./share";
+export type { SharePolicy } from "./share";
+export { recordChatFeedback } from "./feedback";
+export type { ChatFeedback, RecordChatFeedbackResult } from "./feedback";
+export {
+  createChatAttachmentHandler,
+  createChatUploadHandler,
+} from "./attachments";
+export type {
+  ChatAttachmentHandler,
+  ChatUploadHandler,
+  ChatUploadResult,
+} from "./attachments";
+
+export { CHAT_ERROR_CODES, parseChatError, isChatDataPart } from "./client";
+export type {
+  ChatErrorBody,
+  ChatErrorCode,
+  ChatModelOption,
+  ChatQuotaState,
+} from "./client";
+export type {
+  ChatAgentData,
+  ChatArtifactData,
+  ChatAuthorizationData,
+  ChatCompactionData,
+  ChatDataChunk,
+  ChatDataPart,
+  ChatDataPartName,
+  ChatDataParts,
+  ChatMessageMetadata,
+  ChatQuestionData,
+  ChatQuestionOption,
+  ChatStatusData,
+  ChatTaskData,
+  ChatTaskItem,
+  ChatTaskStatus,
+  ChatUIMessage,
+  ChatUIMessageChunk,
+} from "./parts";

package/src/messages.ts

@@ -0,0 +1,39 @@
+/**
+ * Between the rows core stores and the transcript the AI SDK renders.
+ */
+
+import type { UIMessage } from "ai";
+
+type MessageRow = { id: string; role: string; parts: string };
+
+function isChatRole(role: string): role is UIMessage["role"] {
+  return role === "system" || role === "user" || role === "assistant";
+}
+
+/**
+ * Stored `messages.parts` is a JSON string; a
+ * row that fails to parse is dropped rather than failing the whole
+ * conversation. Tool-role rows are not part of the UI transcript.
+ */
+export function toUIMessages(rows: ReadonlyArray<MessageRow>): UIMessage[] {
+  const out: UIMessage[] = [];
+  for (const row of rows) {
+    if (!isChatRole(row.role)) continue;
+    try {
+      const parts = JSON.parse(row.parts) as unknown;
+      if (!Array.isArray(parts)) continue;
+      out.push({ id: row.id, role: row.role, parts });
+    } catch {
+      // A corrupt row costs one message, not the conversation.
+    }
+  }
+  return out;
+}
+
+/** The last message when it is the user's turn, else null. */
+export function lastUserMessage(
+  messages: ReadonlyArray<UIMessage>
+): UIMessage | null {
+  const last = messages[messages.length - 1];
+  return last?.role === "user" ? last : null;
+}

package/src/parts.ts

@@ -0,0 +1,143 @@
+/**
+ * The parts vocabulary a chat UI, a tool and a runtime binding share. The
+ * AI SDK's own parts render as they arrive; a `data-chat-*` part exists only
+ * where the SDK has nothing (a deferred title, a status line, a task plan, a
+ * subagent, a canvas document, a question, an authorization). Type-only.
+ */
+
+import type { DataUIPart, UIMessage, UIMessageChunk } from "ai";
+
+import type { TokenUsage } from "./usage";
+
+/** A live line under the reply — "Searching the web…". One per `id`; transient. */
+export type ChatStatusData = {
+  label: string;
+  phase?: "thinking" | "searching" | "tool" | "writing";
+  done?: boolean;
+};
+
+export type ChatTaskStatus = "pending" | "in_progress" | "done" | "failed";
+
+export type ChatTaskItem = {
+  id: string;
+  title: string;
+  status: ChatTaskStatus;
+};
+
+/** A plan the agent is working through. Reconciled by `id`; persisted. */
+export type ChatTaskData = {
+  id: string;
+  title: string;
+  status: ChatTaskStatus;
+  items?: ChatTaskItem[];
+};
+
+/** A delegated agent — eve's `subagent.*`, Mastra's networks and nested agents. */
+export type ChatAgentData = {
+  id: string;
+  name: string;
+  status: "started" | "completed" | "failed";
+  parentId?: string;
+  summary?: string;
+};
+
+/**
+ * A document streaming into the canvas. Deltas travel as transient
+ * parts under the same `id`; the final `ready` part is persisted so the
+ * card reopens the document after a reload.
+ */
+export type ChatArtifactData = {
+  id: string;
+  kind: string;
+  title: string;
+  status: "streaming" | "ready" | "error";
+  documentId?: string;
+  version?: number;
+  /** The whole content, when the writer was asked to persist it. */
+  content?: string;
+  /** One streamed increment; only on transient parts. */
+  delta?: string;
+  error?: string;
+};
+
+export type ChatQuestionOption = {
+  id: string;
+  label: string;
+  description?: string;
+};
+
+/** A runtime paused for an answer that is not a tool approval. */
+export type ChatQuestionData = {
+  id: string;
+  prompt: string;
+  options?: ChatQuestionOption[];
+  allowFreeform?: boolean;
+  multiple?: boolean;
+  answered?: boolean;
+  answer?: string;
+};
+
+/** A connection that needs the user to sign in before the run continues. */
+export type ChatAuthorizationData = {
+  id: string;
+  name: string;
+  status: "required" | "completed";
+  description?: string;
+  instructions?: string;
+  url?: string;
+};
+
+export type ChatCompactionData = { status: "requested" | "completed" };
+
+export type ChatDataParts = {
+  /** A title written after the first reply. Transient. */
+  "chat-title": string;
+  "chat-status": ChatStatusData;
+  "chat-task": ChatTaskData;
+  "chat-agent": ChatAgentData;
+  "chat-artifact": ChatArtifactData;
+  "chat-question": ChatQuestionData;
+  "chat-authorization": ChatAuthorizationData;
+  "chat-compaction": ChatCompactionData;
+  /** A structured result the turn was asked for. */
+  "chat-result": unknown;
+};
+
+export type ChatDataPartName = keyof ChatDataParts;
+
+/** What the transport attaches to an assistant message once it finishes. */
+export type ChatMessageMetadata = {
+  modelId?: string;
+  usage?: TokenUsage;
+  /** ISO-8601. */
+  finishedAt?: string;
+  /** The reader's feedback, folded in by the UI from the votes table. */
+  vote?: "up" | "down";
+};
+
+export type ChatUIMessage = UIMessage<ChatMessageMetadata, ChatDataParts>;
+
+export type ChatDataPart = DataUIPart<ChatDataParts>;
+
+export type ChatUIMessageChunk = UIMessageChunk<
+  ChatMessageMetadata,
+  ChatDataParts
+>;
+
+/** The chunks a tool or a binding may write mid-turn through `turn.write`. */
+export type ChatDataChunk = Extract<
+  ChatUIMessageChunk,
+  { type: `data-${string}` }
+>;
+
+/** Narrow an unknown part to one of this vocabulary's data parts. */
+export function isChatDataPart<NAME extends ChatDataPartName>(
+  part: unknown,
+  name: NAME
+): part is { type: `data-${NAME}`; id?: string; data: ChatDataParts[NAME] } {
+  return (
+    typeof part === "object" &&
+    part !== null &&
+    (part as { type?: unknown }).type === `data-${name}`
+  );
+}

package/src/quota.ts

@@ -0,0 +1,105 @@
+/**
+ * What the chat page knows about the caller's credit before they type, so
+ * it can say so before a turn is refused with 402. An estimate, never a
+ * reservation: rendering a page cannot consume credit.
+ */
+
+import { requireWorkspace } from "@intelligo-dev/auth";
+import { estimateQuota } from "@intelligo-dev/billing";
+import { createLogger } from "@intelligo-dev/core/logger";
+
+import type { ChatQuotaState } from "./client";
+
+const log = createLogger("ChatQuota");
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function readState(
+  workspaceId: string,
+  modelId: string,
+  upgradeHref: string
+): Promise<ChatQuotaState> {
+  const quota = await estimateQuota(workspaceId, { modelId });
+  if (quota.code === "unknown_model") {
+    // A deployment error, not the reader's balance: the page shows
+    // neutral copy, and this line is where the operator finds out.
+    log.error("Model has no registered price", {
+      modelId,
+      reason: quota.reason,
+    });
+  }
+  return {
+    allowed: quota.allowed,
+    reason: quota.reason ?? null,
+    code: quota.code ?? null,
+    // Micros of the deployment's billing currency.
+    remaining: quota.remaining?.amount ?? 0,
+    estimated: quota.estimated?.amount ?? 0,
+    upgradeHref,
+  };
+}
+
+/**
+ * Never throws: the page renders with or without this. A quota read
+ * that fails should cost the reader a banner, not the conversation.
+ */
+export async function getChatQuotaState(options: {
+  /** The model a turn would run on — what the estimate is priced against. */
+  modelId: string;
+  /** Where "upgrade" and "top up" should go. */
+  upgradeHref: string;
+  /** Defaults to the request's workspace. */
+  workspaceId?: string;
+}): Promise<ChatQuotaState | null> {
+  try {
+    const workspaceId =
+      options.workspaceId ?? (await requireWorkspace()).workspace.id;
+    return await readState(workspaceId, options.modelId, options.upgradeHref);
+  } catch (error) {
+    log.warn("quota state unavailable", { error: errorMessage(error) });
+    return null;
+  }
+}
+
+/**
+ * The same estimate for each model the composer offers, keyed by model
+ * id, so the banner can follow the picker: a turn on a dearer model has
+ * a larger worst case, and the balance that funds one may not fund the
+ * other. Never throws; a model whose read failed is left out.
+ */
+export async function getChatQuotaStates(options: {
+  modelIds: readonly string[];
+  /** Where "upgrade" and "top up" should go. */
+  upgradeHref: string;
+  /** Defaults to the request's workspace. */
+  workspaceId?: string;
+}): Promise<Record<string, ChatQuotaState>> {
+  const modelIds = [...new Set(options.modelIds)];
+  if (modelIds.length === 0) return {};
+  try {
+    const workspaceId =
+      options.workspaceId ?? (await requireWorkspace()).workspace.id;
+    const entries = await Promise.all(
+      modelIds.map(async (modelId) => {
+        try {
+          return [
+            modelId,
+            await readState(workspaceId, modelId, options.upgradeHref),
+          ] as const;
+        } catch (error) {
+          log.warn("quota state unavailable", {
+            modelId,
+            error: errorMessage(error),
+          });
+          return null;
+        }
+      })
+    );
+    return Object.fromEntries(entries.filter((entry) => entry !== null));
+  } catch (error) {
+    log.warn("quota state unavailable", { error: errorMessage(error) });
+    return {};
+  }
+}

package/src/share.ts

@@ -0,0 +1,103 @@
+/**
+ * What a public, read-only copy of a conversation may show.
+ *
+ * A shared page renders the same transcript the owner sees, minus what
+ * was never meant for a stranger: the model's reasoning, the raw input
+ * and output of every tool, provider metadata, token usage, transient
+ * runtime parts, and any file URL — a stored attachment's URL is a
+ * tenant-scoped, short-lived signed link, and an inline one is the
+ * whole file. A product that wants a named tool's output on the shared
+ * page (a report card, say) lists it in the policy.
+ *
+ * Pure: no I/O, no `ai` import at runtime.
+ */
+
+import type { UIMessage } from "ai";
+
+export type SharePolicy = {
+  /** Tool names whose `input`/`output` stay on the shared page. */
+  keepToolOutput?: readonly string[];
+  /** `data-*` part names (without the prefix) that stay. Default: `chat-task`, `chat-artifact`. */
+  keepDataParts?: readonly string[];
+  /** Keep reasoning parts. Default false. */
+  keepReasoning?: boolean;
+};
+
+const DEFAULT_DATA_PARTS: readonly string[] = ["chat-task", "chat-artifact"];
+
+function toolNameOf(part: Record<string, unknown>): string | null {
+  if (part.type === "dynamic-tool" && typeof part.toolName === "string") {
+    return part.toolName;
+  }
+  if (typeof part.type === "string" && part.type.startsWith("tool-")) {
+    return part.type.slice("tool-".length);
+  }
+  return null;
+}
+
+export function sanitizeForShare(
+  messages: ReadonlyArray<UIMessage>,
+  policy: SharePolicy = {}
+): UIMessage[] {
+  const keepTools = new Set(policy.keepToolOutput ?? []);
+  const keepData = new Set(policy.keepDataParts ?? DEFAULT_DATA_PARTS);
+
+  return messages.map((message) => {
+    const parts: UIMessage["parts"] = [];
+    for (const raw of message.parts) {
+      const part = raw as unknown as Record<string, unknown>;
+      const type = typeof part.type === "string" ? part.type : "";
+
+      if (type === "reasoning") {
+        if (policy.keepReasoning) parts.push(raw);
+        continue;
+      }
+      if (type === "text" || type === "step-start") {
+        const { providerMetadata: _pm, ...rest } = part;
+        parts.push(rest as unknown as UIMessage["parts"][number]);
+        continue;
+      }
+      if (type === "source-url" || type === "source-document") {
+        const { providerMetadata: _pm, ...rest } = part;
+        parts.push(rest as unknown as UIMessage["parts"][number]);
+        continue;
+      }
+      if (type === "file") {
+        parts.push({
+          type: "file",
+          mediaType: String(part.mediaType ?? "application/octet-stream"),
+          ...(typeof part.filename === "string"
+            ? { filename: part.filename }
+            : {}),
+          url: "",
+        });
+        continue;
+      }
+      const toolName = toolNameOf(part);
+      if (toolName !== null) {
+        const kept = keepTools.has(toolName);
+        const {
+          input,
+          output,
+          errorText: _e,
+          providerMetadata: _pm,
+          callProviderMetadata: _cpm,
+          providerExecuted: _pe,
+          approval: _a,
+          ...rest
+        } = part;
+        parts.push({
+          ...rest,
+          ...(kept && input !== undefined ? { input } : {}),
+          ...(kept && output !== undefined ? { output } : {}),
+        } as unknown as UIMessage["parts"][number]);
+        continue;
+      }
+      if (type.startsWith("data-")) {
+        if (keepData.has(type.slice("data-".length))) parts.push(raw);
+        continue;
+      }
+    }
+    return { id: message.id, role: message.role, parts };
+  });
+}

package/src/testing.ts

@@ -0,0 +1,150 @@
+/**
+ * A deterministic language model (from `ai/test`) that streams end to end
+ * before any provider is configured; the transport's own tests use it too.
+ * `modelId` is a parameter, never a literal: the boundary bills whatever id
+ * the transport settles with, so it must be registered in the pricing table.
+ */
+
+import type { LanguageModel } from "ai";
+import { MockLanguageModelV3, simulateReadableStream } from "ai/test";
+
+/** A model prompt as the stub sees it: the AI SDK's provider-level shape. */
+export type StubPrompt = ReadonlyArray<{ role: string; content: unknown }>;
+
+export type StubToolCall = {
+  toolName: string;
+  /** Must satisfy the tool's input schema. */
+  input: Record<string, unknown>;
+};
+
+export type StubLanguageModelOptions = {
+  /** Reported to the boundary; must be a registered model id. */
+  modelId: string;
+  /** The reply, from the last user message's text. */
+  reply: (lastUserText: string, prompt: StubPrompt) => string | Promise<string>;
+  /**
+   * A tool call to emit alongside the reply, or null for none. Lets a
+   * stub exercise the whole tool path — call, execute, render — with
+   * no provider. Called once per step; return null on the follow-up
+   * step (the prompt then carries the earlier call) to end the turn.
+   */
+  toolCall?: (
+    lastUserText: string,
+    prompt: StubPrompt
+  ) => StubToolCall | null | Promise<StubToolCall | null>;
+  /** Delay between tokens, in ms. Default 15; 0 in tests. */
+  chunkDelayInMs?: number;
+};
+
+/**
+ * Structurally the provider spec's `LanguageModelV3StreamPart`, for
+ * the variants this stub emits, without importing `@ai-sdk/provider`
+ * — a transitive dependency of `ai`, not one this package declares.
+ */
+type StubStreamPart =
+  | { type: "stream-start"; warnings: never[] }
+  | { type: "text-start"; id: string }
+  | { type: "text-delta"; id: string; delta: string }
+  | { type: "text-end"; id: string }
+  | {
+      type: "tool-call";
+      toolCallId: string;
+      toolName: string;
+      /** Stringified JSON matching the tool's input schema. */
+      input: string;
+    }
+  | {
+      type: "finish";
+      finishReason: { unified: "stop" | "tool-calls"; raw: undefined };
+      usage: {
+        inputTokens: {
+          total: number;
+          noCache: undefined;
+          cacheRead: undefined;
+          cacheWrite: undefined;
+        };
+        outputTokens: { total: number; text: number; reasoning: undefined };
+      };
+    };
+
+/** The last user message's text, from a provider-level prompt. */
+export function lastUserTextOf(prompt: StubPrompt): string {
+  for (let i = prompt.length - 1; i >= 0; i--) {
+    const message = prompt[i];
+    if (message?.role !== "user") continue;
+    const parts = Array.isArray(message.content) ? message.content : [];
+    return parts
+      .filter(
+        (part): part is { type: "text"; text: string } =>
+          typeof part === "object" &&
+          part !== null &&
+          (part as { type?: unknown }).type === "text"
+      )
+      .map((part) => part.text)
+      .join(" ");
+  }
+  return "";
+}
+
+export function createStubLanguageModel(
+  options: StubLanguageModelOptions
+): LanguageModel {
+  const delay = options.chunkDelayInMs ?? 15;
+  return new MockLanguageModelV3({
+    provider: "stub",
+    modelId: options.modelId,
+    doStream: async ({ prompt }) => {
+      const userText = lastUserTextOf(prompt);
+      const reply = await options.reply(userText, prompt);
+      const call = options.toolCall
+        ? await options.toolCall(userText, prompt)
+        : null;
+      const words = reply.split(" ");
+
+      const chunks: StubStreamPart[] = [
+        { type: "stream-start", warnings: [] },
+        { type: "text-start", id: "1" },
+        ...words.map<StubStreamPart>((word, index) => ({
+          type: "text-delta",
+          id: "1",
+          delta: index === 0 ? word : ` ${word}`,
+        })),
+        { type: "text-end", id: "1" },
+        ...(call
+          ? [
+              {
+                type: "tool-call" as const,
+                toolCallId: `stub-${Date.now()}`,
+                toolName: call.toolName,
+                input: JSON.stringify(call.input),
+              },
+            ]
+          : []),
+        {
+          type: "finish",
+          finishReason: {
+            unified: call ? "tool-calls" : "stop",
+            raw: undefined,
+          },
+          usage: {
+            inputTokens: {
+              total: Math.max(1, Math.ceil(JSON.stringify(prompt).length / 4)),
+              noCache: undefined,
+              cacheRead: undefined,
+              cacheWrite: undefined,
+            },
+            outputTokens: {
+              total: words.length,
+              text: words.length,
+              reasoning: undefined,
+            },
+          },
+        },
+      ];
+
+      return {
+        stream: simulateReadableStream({ chunkDelayInMs: delay, chunks }),
+      };
+    },
+  });
+}

package/src/title.ts

@@ -0,0 +1,15 @@
+/**
+ * The default conversation title: the first line of the opening
+ * message, truncated to something a sidebar can list.
+ */
+
+const MAX_TITLE_LENGTH = 60;
+
+/** First line, trimmed, truncated — enough to tell history rows apart. */
+export function truncateTitle(firstUserText: string): string | null {
+  const line = firstUserText.trim().split("\n")[0]?.trim();
+  if (!line) return null;
+  return line.length <= MAX_TITLE_LENGTH
+    ? line
+    : `${line.slice(0, MAX_TITLE_LENGTH - 1).trimEnd()}…`;
+}

package/src/usage.ts

@@ -0,0 +1,46 @@
+/**
+ * Token usage, in the one shape the execution boundary settles.
+ */
+
+export type TokenUsage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+};
+
+/** The three fields settlement reads, and nothing else a provider adds. */
+export function pickUsage(usage: TokenUsage | undefined): TokenUsage {
+  return {
+    inputTokens: usage?.inputTokens,
+    outputTokens: usage?.outputTokens,
+    totalTokens: usage?.totalTokens,
+  };
+}
+
+/**
+ * Whole-run usage from the steps that completed before an abort. A
+ * step still in flight is missed — under-counting by at most one step
+ * beats charging nothing and leaving the hold to expire.
+ */
+export function sumStepUsage(
+  steps: ReadonlyArray<{ usage?: TokenUsage }>
+): TokenUsage {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  for (const step of steps) {
+    inputTokens += step.usage?.inputTokens ?? 0;
+    outputTokens += step.usage?.outputTokens ?? 0;
+  }
+  return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+}
+
+/** The sum of two usages; a total a provider omitted is input plus output. */
+export function sumUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+  const total = (u: TokenUsage) =>
+    u.totalTokens ?? (u.inputTokens ?? 0) + (u.outputTokens ?? 0);
+  return {
+    inputTokens: (a.inputTokens ?? 0) + (b.inputTokens ?? 0),
+    outputTokens: (a.outputTokens ?? 0) + (b.outputTokens ?? 0),
+    totalTokens: total(a) + total(b),
+  };
+}