@adriangalilea/utils 1.15.0 → 2.0.0

package/README.md

@@ -281,7 +281,8 @@ Every `SourcedError` carries `source`, `operation`, `status`, `context`, and the
 - **XDG**: XDG Base Directory paths — reads env vars set by [xdg-dirs](https://github.com/adriangalilea/xdg-dirs), falls back to spec defaults
 - **Unseen**: Persistent dedup filter — "what's new since last time?" for cron/monitoring workflows
 - **Project Discovery**: Find project/monorepo roots, detect JS/TS projects
-- **Bot plugins (GramIO)**: `kit` (graceful shutdown + admin context), `access-control` (gate + approve/deny menu, backed by sessions), `llm` (OpenAI-compat SSE parser `streamChat` + Telegram streaming output `ctx.startStream` + per-thread conversation history `ctx.llm`), `payments` (Telegram Stars: VIP tiers + credits + perks + waiver + refund flow, ToS-compliant, Spanish-autónomo-aware), `coalesce`, `language`, `menu`
+- **LLM caller (`llm`)**: multi-provider failover on top of the Vercel AI SDK — priority ordering, per-key circuit breaker (KV-backed), reset events for live previews, usage accounting with actual billed cost (OpenRouter), tool calling. Worker-safe.
+- **Bot plugins (GramIO)**: `kit` (graceful shutdown + admin context), `access-control` (gate + approve/deny menu, backed by sessions), `llm` (draft-streamed replies `streamChatReply` + per-thread conversation history `ctx.llm`), `payments` (Telegram Stars: VIP tiers + credits + perks + waiver + refund flow, ToS-compliant, Spanish-autónomo-aware), `coalesce`, `language`, `menu`
 
 ### XDG Base Directories
 
@@ -447,7 +448,8 @@ Then `pnpm install`. Every `ctx.send` / `ctx.sendDocument` / `ctx.reply` / etc.
 | `@adriangalilea/utils/bot/language` (picker surface) | The language-picker vocabulary and surfaces, so bots don't fork label lists: `flagFor` / `autonym` / `languageLabel` ("🇪🇸 Español"), `languagePickerItem({ label, codes, isActive, pick })` (the 2-up primary-highlighted MenuItem factory — storage and policy live in your closures), and `addLanguageRows(kb, { codes, pack, active?, activeStyle? })` (the raw-InlineKeyboard twin for onboarding / group-welcome keyboards; `activeStyle: "success"` when primary already marks something else on the keyboard). |
 | `@adriangalilea/utils/bot/user` | `userLabel(u)` — the conditional "[name] [@username] [id]" line every bot re-rolls for admin DMs and logs: `Ada Lovelace (@ada · 42)` / `Ada (42)` / `@ada (42)` / `id 42`, missing pieces drop instead of padding. Reads both gramio spellings (`firstName` / `first_name`); plain text by design. |
 | `@adriangalilea/utils/bot/coalesce` | Joins client-split inbound messages back into one. When a user pastes >4096 chars, Telegram clients fragment it into separate `message` updates with no marker. Middleware detects the burst and emits one combined event. |
-| `@adriangalilea/utils/bot/llm` | The full LLM-chatbot pipeline in one module. **Input:** `streamChat(response)` parses OpenAI-compatible SSE (OpenAI, vllm, mlx-lm, llama.cpp, Together, Groq, …) into a typed `AsyncGenerator<{type: 'content' \| 'reasoning', text}>`. **Output:** `ctx.startStream()` (low-level: debounced markdown to Telegram, 4000-char split, exposes `wasPartial` after `.end()`). `ctx.startChatStream(response)` (high-level: consumes the stream, renders reasoning as a Telegram `expandable_blockquote` entity + content as streamed markdown — both go through `markdownToFormattable` with graceful degradation — returns `{ content, reasoning }`). **History:** `llmHistory({...})` returns `.plugin` (decorates `ctx.llm` with `.add() / .get() / .clear() / .all() / .clearAll()`, per-(user, thread) OpenAI `ChatMessage` shape, persisted in the shared session record so the menu's 🗑 Forget wipes it automatically) AND `.menuItem` (drop-in "🗑 Delete this thread" for `botMenu` — wipes the LLM history AND calls `deleteForumTopic` so the Telegram thread + all its messages disappear from the chat; falls back to Redis-only clear when no `threadId` is present). |
+| `@adriangalilea/utils/llm` | Multi-provider LLM caller on the Vercel AI SDK — the policy layer the SDK doesn't ship. `createLlm({ providers, health? })` → `.stream(req)` (typed events: `delta` / `reasoning` / `reset` / `tool-call` / `end`) and `.complete(req)`. **Failover:** priority-ordered across OpenAI-compatible, Anthropic-compatible, and OpenRouter endpoints; multiple keys per provider (health tracked per key fingerprint); per-key circuit breaker with exponential cool-down persisted in any KV-shaped `HealthStore`; an attempt that dies after emitting yields `reset` (discard, next candidate regenerates); empty completions count as failures. **Accounting:** tokens summed across billed attempts; `costUsd` is the ACTUAL charge (OpenRouter usage accounting via `providerMetadata`, or a `cost` field on the raw usage frame) — never a price-table estimate. **Knobs:** per-model temperature, maxTokens caps, `disableThinking` mapped to each dialect. **Tools:** AI SDK `tool()` + `toolChoice` pass through (re-exported). Worker-safe; peers: `ai`, `@ai-sdk/openai-compatible`, `@ai-sdk/anthropic`, `@openrouter/ai-sdk-provider`. |
+| `@adriangalilea/utils/bot/llm` | The Telegram side of an LLM chatbot; the model side is `@adriangalilea/utils/llm`. **Output:** `streamChatReply(ctx, events, opts?)` consumes an `AsyncIterable<LlmStreamEvent>` and paints it with Telegram's native message-draft streaming (`sendMessageDraft` full-frame repaints, throttled ~1/s, keepalive under the ~30s draft TTL), then persists the finished markdown via `ctx.send`, entity-split across 4096 by `@gramio/split`. Reasoning models get a thinking phase — streams into the ephemeral draft and evaporates (`reasoning: 'preview'`, default), persists as an expandable blockquote (`'message'`), or never renders (`'hidden'`). Upstream `reset` (provider failover) repaints the draft from scratch. Drafts are private-chat-only (+ BotFather forum-topic mode); elsewhere the preview phase is skipped and only the final send happens. Returns `{ content, reasoning, toolCalls, usage, messages }`. **History:** `llmHistory({...})` returns `.plugin` (decorates `ctx.llm` with `.add() / .get() / .clear() / .all() / .clearAll()`, per-(user, thread) OpenAI `ChatMessage` shape, persisted in the shared session record so the menu's 🗑 Forget wipes it automatically) AND `.menuItem` (drop-in "🗑 Delete this thread" for `botMenu` — wipes the LLM history AND calls `deleteForumTopic` so the Telegram thread + all its messages disappear from the chat; falls back to history-only clear when no `threadId` is present). |
 | `@adriangalilea/utils/bot/menu` | `botMenu({ command, description, items, privacy?, personalData?, adminContact })` — `/settings` command + InlineKeyboard router. Root view always renders a `🛡️ Privacy & data` submenu button that wraps the privacy policy link plus (if `personalData: { storage }`) 🗑 Forget + 📥 Export buttons. Items take `keepRow` (render on the same row as the next item — e.g. a two-per-row language picker) and `rootExtra` (render at the bottom of the root menu, below Privacy & data). `label` / `header` / `style` / `visible` resolvers may be **async** (read your db at render time — never cache render strings in the session); `parseMode: 'HTML'` renders the header formatted (you own escaping); `personalData.onForget(ctx, userId)` wipes YOUR tables inside the same try as the session delete, so Forget either forgets everything or reports failure. `toggleMenuItem({ id, read, write, label: { off, on }, toast? })` — convenience factory for boolean-toggle items with dynamic label + optional toast, storage-agnostic via `read`/`write` closures. |
 | `@adriangalilea/utils/bot/payments` | `botPayments({ session, storage, paysupport, paysupportHint?, legal, waiver, vip?, credits?, perks? })` — Telegram Stars monetization in one drop-in plugin. **Three axes, all optional:** `vip` (positional tier ladder — single rung in v1 is just `vip: [{...}]`, ladder is `vip: [{...}, {...}]`; ids are `vip.1`, `vip.2`, …), `credits` (consumable balance + top-up packs `credits.1`, `credits.2`, …), `perks` (orthogonal one-shot unlocks `perks.<key>`). **Surface:** `ctx.payments.atLeast('vip')` / `atLeast('vip.2')` (typed rank check), `ctx.payments.tier()` / `.tier.level()` / `.tier.label()`, `ctx.payments.credits.{balance, consume, tryConsume}` (throws `InsufficientCredits`), `ctx.payments.has(perkId)`, `await ctx.payments.require('vip', { feature? })` (gate that sends a localized upgrade prompt deep-linked to `/settings → 💎 VIP`), `await ctx.payments.invoice(productKey)` (threads Art. 103(m) TRLGDCU consent inline before `sendInvoice`). **Owns:** waiver consent flow (versioned text → forces re-consent on bump, snapshotted on every charge for audit), `/paysupport` slash command (Telegram ToS §6.5; `paysupportHint` overrides the where-to-manage-charges line when your menu isn't `/settings`), idempotent `successful_payment` fulfillment via `pay:idempotency:{chargeId}` sentinel, lazy subscription expiry (no cron needed), tier upgrade auto-cancel of the lower rung's renewal, and admin-DM refund approval (mirror of `accessControl`'s [✅ Aprobar][❌ Denegar] pattern). **Returns:** `{ plugin, menuItem, payouts, onFulfilled }` — `menuItem` is the drop-in `💎 VIP` entry for `botMenu`; `payouts.{record, list, export, exportForUsers}` is the Fragment payout ledger (you receive TON, log the EUR conversion, export time-windowed CSV/JSON for your gestor); `onFulfilled(productKey \| '*', handler)` / `onRefunded(...)` register fire-and-forget hooks (purchase applied / admin-approved refund — a revenue ledger writes on one, reverses on the other). **Stars-only by design** — Telegram ToS §6.2 forbids third-party payment providers for digital goods. Crypto Pay deferred (MiCA risk); Stripe-outside-Telegram is a future v2 channel. Full compliance memo (Spanish-autónomo seller-of-record analysis, Verifactu vs Crea y Crece, MiCA, Art. 103(m) waiver text, GDPR retention) in `src/bot/payments/CLAUDE.md`. |
 | `@adriangalilea/utils/bot/create` | `createBot<S>({ token?, storage?, initial?, admins?, language?, menu?, access?, payments?, handlers?, worker? })` — the composer (see "One bot file, ideation → production" above). Returns `{ build, session, poll, isMain, fetch }`: `poll()` long-polls, `export default app` is a complete Worker, `app.session(ctx)` / the `handlers` callback's `session(ctx)` is the TYPED accessor for your `S` fields. Owns storage+session wiring; resolves storage per environment (D1 binding → `bot/storage-d1`; `BOT_PERSIST` path → sqlite, `redis://` → redis, lazily-imported optional peers; else announced-ephemeral memory) — or pass `storage: (env) => Storage` when the choice is env-dependent (e.g. a D1 binding not named `DB`). Boot NARRATES the composition (`session: memory …`, `features: language(en,es) · menu(/settings)`) so every implicit decision is visible where you're looking. Runnable demo: `pnpm demo:bot`. |
@@ -463,7 +465,8 @@ import { redisStorage } from '@gramio/storage-redis'
 import { adminContext, gracefulStart } from '@adriangalilea/utils/bot/kit'
 import { botSession } from '@adriangalilea/utils/bot/session'
 import { accessControl } from '@adriangalilea/utils/bot/access-control'
-import { llmStream, llmHistory } from '@adriangalilea/utils/bot/llm'
+import { createLlm } from '@adriangalilea/utils/llm'
+import { streamChatReply, llmHistory, toModelMessages } from '@adriangalilea/utils/bot/llm'
 
 // Raw redis is fine — bot-id namespacing happens inside botSession +
 // every plugin via ctx.bot.info.id. Multiple bots sharing this Redis
@@ -472,29 +475,26 @@ const storage = redisStorage()
 const userSession = botSession({ storage, key: 'session', initial: () => ({}) })
 const chat = llmHistory({ session: userSession, maxTurns: 20, retentionDays: 7 })
 
+// Any OpenAI-compatible endpoint: vllm-mlx, mlx-lm, llama.cpp, Together, Groq, OpenAI, …
+// More entries = priority failover; a KV-shaped `health` store adds the circuit breaker.
+const llm = createLlm({
+  providers: [{ id: 'local', type: 'openai', baseUrl: process.env.LLM_URL!, apiKey: 'none', defaultModel: process.env.LLM_MODEL! }],
+})
+
 const bot = new Bot(process.env.BOT_TOKEN!)
   .extend(adminContext({ adminId: 190202471 }))     // KEV.TELEGRAM_ADMIN_ID overrides
   .extend(userSession)
   .extend(accessControl({ session: userSession, storage, defaults: [] }))
-  .extend(llmStream())
   .extend(chat.plugin)
   .on('message', async (ctx) => {
     if (!ctx.access.allowed) return
     ctx.llm.add({ role: 'user', content: ctx.text ?? '' })
 
-    // Any OpenAI-compatible endpoint: vllm-mlx, mlx-lm, llama.cpp, Together, Groq, OpenAI, …
-    const response = await fetch(process.env.LLM_URL!, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        model: process.env.LLM_MODEL,
-        messages: [{ role: 'system', content: 'You are helpful.' }, ...ctx.llm.get()],
-        stream: true,
-      }),
-    })
-
-    // High-level: handles reasoning (collapsed blockquote) + content streaming.
-    const { content } = await ctx.startChatStream(response)
+    // Draft-streamed reply: thinking phase previews + final entity-split send.
+    const { content } = await streamChatReply(ctx, llm.stream({
+      instructions: 'You are helpful.',
+      messages: toModelMessages(ctx.llm.get()),
+    }))
     ctx.llm.add({ role: 'assistant', content })
   })
 

package/dist/bot/index.d.ts

@@ -6,7 +6,7 @@
  *
  *   import { adminContext, gracefulStart } from '@adriangalilea/utils/bot/kit'
  *   import { accessControl } from '@adriangalilea/utils/bot/access-control'
- *   import { llmStream } from '@adriangalilea/utils/bot/llm'
+ *   import { streamChatReply, llmHistory } from '@adriangalilea/utils/bot/llm'
  *
  * Or all-in-one (pulls every subpath):
  *   import { ... } from '@adriangalilea/utils/bot'

package/dist/bot/index.js

@@ -6,7 +6,7 @@
  *
  *   import { adminContext, gracefulStart } from '@adriangalilea/utils/bot/kit'
  *   import { accessControl } from '@adriangalilea/utils/bot/access-control'
- *   import { llmStream } from '@adriangalilea/utils/bot/llm'
+ *   import { streamChatReply, llmHistory } from '@adriangalilea/utils/bot/llm'
  *
  * Or all-in-one (pulls every subpath):
  *   import { ... } from '@adriangalilea/utils/bot'

package/dist/bot/llm.d.ts

@@ -1,248 +1,86 @@
 /**
- * GramIO LLM toolkit — three primitives that together form a complete
- * Telegram LLM-chatbot pipeline:
+ * GramIO LLM toolkit — the Telegram side of an LLM chatbot. The model side
+ * (providers, failover, usage accounting, tools) lives in
+ * `@adriangalilea/utils/llm`; this module renders its event stream into a
+ * chat and remembers conversations:
  *
- *   `streamChat(response)`   — INPUT. Parses OpenAI-compatible SSE
- *                              (OpenAI, vllm, mlx-lm, llama.cpp,
- *                              Together, Groq, …) into a typed
- *                              `AsyncGenerator` of `{type, text}` with
- *                              `content` / `reasoning` separation.
- *
- *   `ctx.startStream()`      — OUTPUT (low-level). Debounced
- *                              `editMessageText` to Telegram, local
- *                              Markdown parse via `@gramio/format`,
- *                              4000-char split on paragraph / line /
- *                              word boundary.
- *
- *   `ctx.startChatStream()`  — OUTPUT (high-level). Consumes a fetch
- *                              `Response` (or any `AsyncIterable<LLMChunk>`)
- *                              and renders BOTH phases of a thinking
- *                              model: `reasoning` chunks go into one
- *                              `<blockquote expandable>` message;
- *                              `content` chunks go into a streamed
- *                              markdown message below it. Returns
- *                              `{ content, reasoning }` once the
- *                              source generator ends.
+ *   `streamChatReply(ctx, events)` — OUTPUT. Consumes an
+ *       `AsyncIterable<LlmStreamEvent>` and paints it with Telegram's native
+ *       message-draft streaming (`sendMessageDraft`: ephemeral ~30s previews,
+ *       animated in place per draft_id), then persists the finished text via
+ *       `ctx.send`, entity-split across the 4096 limit by `@gramio/split`.
+ *       Reasoning models get a "thinking" phase: reasoning streams into the
+ *       draft preview and evaporates by default, or persists as an expandable
+ *       blockquote. A `reset` event (provider failover upstream) repaints the
+ *       draft from scratch — full-frame previews make that one cheap frame.
+ *       Drafts are a PRIVATE-chat capability (and the bot needs forum topic
+ *       mode enabled in BotFather); elsewhere the preview phase is skipped and
+ *       only the final send happens.
  *
  *   `ctx.llm.add / .get / …` — HISTORY. Per-(user, thread) conversation
- *                              buffer in OpenAI `ChatMessage` shape.
- *                              Persisted in the shared `@gramio/session`
- *                              record under the `llm` field, so the
- *                              `botMenu` 🗑 Forget button wipes it
- *                              together with everything else (one
- *                              record, one delete, no per-plugin
- *                              registry).
- *
- * The trio composes:
+ *       buffer in OpenAI `ChatMessage` shape, persisted in the shared
+ *       `@gramio/session` record under the `llm` field, so the `botMenu`
+ *       🗑 Forget button wipes it together with everything else.
  *
- *     fetch(...) ──streamChat──> chunks ──ctx.startStream──> Telegram
- *           ▲                                                   │
- *           └──── ctx.llm.get() ◀──── ctx.llm.add(assistant) ◀──┘
+ * Peer deps: `gramio`, `@gramio/session`, `@gramio/format`, `@gramio/split`,
+ * `marked`.
  *
- * Peer deps: `gramio`, `@gramio/session`, `@gramio/format`, `marked`.
+ * @example  chatbot turn: history → llm.stream → streamed reply
+ * import { createLlm } from '@adriangalilea/utils/llm'
+ * import { streamChatReply, llmHistory, toModelMessages } from '@adriangalilea/utils/bot/llm'
  *
- * @example  high-level — thinking model in ~10 LOC
- * import { Bot } from 'gramio'
- * import { session } from '@gramio/session'
- * import { llmStream, llmHistory } from '@adriangalilea/utils/bot/llm'
- *
- * const userSession = session({ storage, key: 'session', initial: () => ({}) })
+ * const llm = createLlm({ providers })
  * const chat = llmHistory({ session: userSession, maxTurns: 20, retentionDays: 7 })
  *
- * const bot = new Bot(process.env.BOT_TOKEN!)
- *   .extend(userSession)
- *   .extend(llmStream())
- *   .extend(chat.plugin)
- *   .on('message', async (ctx) => {
- *     ctx.llm.add({ role: 'user', content: ctx.text ?? '' })
- *     const response = await fetch(process.env.LLM_URL!, {
- *       method: 'POST',
- *       headers: { 'Content-Type': 'application/json' },
- *       body: JSON.stringify({
- *         model: process.env.LLM_MODEL,
- *         messages: [{ role: 'system', content: 'You are helpful.' }, ...ctx.llm.get()],
- *         stream: true,
- *       }),
- *     })
- *     const { content } = await ctx.startChatStream(response)
- *     ctx.llm.add({ role: 'assistant', content })
- *   })
- *
- * bot.start()
- *
- * @example  low-level — manual loop when you need to map/filter chunks
- * import { streamChat } from '@adriangalilea/utils/bot/llm'
- *
- * const stream = ctx.startStream()
- * for await (const chunk of streamChat(response)) {
- *   if (chunk.type === 'content') await stream.append(chunk.text)
- *   // reasoning chunks dropped here
- * }
- * await stream.end()
+ * bot.extend(userSession).extend(chat.plugin).on('message', async (ctx) => {
+ *   ctx.llm.add({ role: 'user', content: ctx.text ?? '' })
+ *   const { content } = await streamChatReply(ctx, llm.stream({
+ *     instructions: 'You are helpful.',
+ *     messages: toModelMessages(ctx.llm.get()),
+ *   }))
+ *   ctx.llm.add({ role: 'assistant', content })
+ * })
  */
 import type { session } from "@gramio/session";
-import { type DeriveDefinitions, Plugin } from "gramio";
+import { type Bot, type DeriveDefinitions, type MessageContext, Plugin } from "gramio";
+import type { LlmStreamEvent, LlmToolCall, LlmUsage, ModelMessage } from "../llm/index.js";
 import type { Polyglot } from "../say/index.js";
 import type { MenuItem } from "./menu.js";
-/**
- * A single chunk yielded by `streamChat`. Two kinds:
- *
- *   - `content`   — the visible reply text the user should see
- *   - `reasoning` — chain-of-thought / "thinking" text from reasoning
- *                   models. Empty unless the model emits it.
- *
- * Most callers care about `content` only. Render `reasoning` separately
- * (collapsed, italicized) if you want to surface thinking.
- */
-export type LLMChunk = {
-    type: "content";
-    text: string;
-} | {
-    type: "reasoning";
-    text: string;
-};
-/**
- * Parse an OpenAI-compatible chat-completions SSE response into a
- * typed `AsyncGenerator<LLMChunk>`. Reads `response.body` once.
- *
- * Recognised reasoning aliases (as of 2026): `reasoning_content`
- * (vllm, qwen3, DeepSeek-R1, gpt-oss harmony) and `reasoning` (some
- * mlx-lm forks, gemma builds). If a model surfaces a new key, add it
- * here — single source of truth for the field.
- *
- * Constrained-SSE assumption: lines are `\n`-delimited and each event
- * is `data: <json>` or `data: [DONE]`. This matches every OpenAI-compat
- * server in the wild but is NOT the full SSE spec (no comments, no
- * multi-line `data:`, no `retry`/`id` fields). Swap to
- * `eventsource-parser` if you hit a producer that needs them.
- *
- * Malformed JSON lines are silently skipped; the generator ends when
- * the stream closes.
- *
- * @param response  the `fetch` `Response` from a `stream: true` chat
- *                  completion call. Must not be already consumed.
- * @throws if `response.body` is null (non-streaming response).
- *
- * @example  framework-agnostic — parser doesn't know about Telegram
- * const res = await fetch(url, { method: 'POST', body })
- * for await (const chunk of streamChat(res)) {
- *   if (chunk.type === 'content') process.stdout.write(chunk.text)
- * }
- */
-export declare function streamChat(response: Response): AsyncGenerator<LLMChunk>;
-export type StreamOptions = {
-    /** Debounce window between edits, in ms. Default 800. */
-    debounceMs?: number;
-    /** Initial placeholder shown until the first chunk arrives. Default "…". */
-    placeholder?: string;
-    /** Parse buffer as markdown. Default true. Set false for plain text streaming. */
-    markdown?: boolean;
-    /** Called on edit/send errors after internal recovery (rate limits, etc.). */
-    onError?: (err: unknown) => void;
-};
-export declare class MarkdownStreamer {
-    private buffer;
-    private currentMessageId?;
-    private firstSendPromise?;
-    private debounceTimer?;
-    private inFlight;
-    private dirty;
-    private ended;
+export interface StreamChatReplyOptions {
     /**
-     * `true` after `.end()` returns if the stream finished with un-flushed
-     * buffer or an outstanding error that the streamer couldn't recover
-     * from. Useful for partial-response diagnostics in catch blocks:
-     *
-     *   try { for await (...) await stream.append(...) }
-     *   finally {
-     *     await stream.end()
-     *     if (stream.wasPartial) logger.warn('LLM stream cut off')
-     *   }
+     * What happens to a reasoning model's thinking text.
+     * `preview` (default) — streams into the ephemeral draft, evaporates when
+     * the answer starts. `message` — additionally persists as an expandable
+     * blockquote message before the answer. `hidden` — never rendered.
      */
-    wasPartial: boolean;
-    private chatId;
-    private threadId?;
-    private bot;
-    private opts;
-    constructor(ctx: {
-        chat: {
-            id: number;
-        };
-        threadId?: number;
-        bot: MarkdownStreamer["bot"];
-    }, opts: StreamOptions);
-    /** Append a chunk. Schedules a debounced edit. */
-    append(text: string): Promise<void>;
-    /** Flush any pending edit and close the stream. Idempotent. */
-    end(): Promise<void>;
-    private scheduleFlush;
-    private flushNow;
+    reasoning?: "preview" | "message" | "hidden";
+    /** Ms between draft repaints. Default 1000. */
+    throttleMs?: number;
+    /**
+     * Extra params for the finalizing `ctx.send` calls (e.g. `reply_markup`).
+     * Applied to the LAST part when the reply splits across messages, so a
+     * keyboard lands at the end.
+     */
+    messageParams?: Parameters<MessageContext<Bot>["send"]>[1];
 }
-/**
- * GramIO plugin. Adds `ctx.startStream(opts?)` on every message context.
- *
- * Defaults set here apply to every stream; per-call options in
- * `ctx.startStream({...})` override them.
- */
-export declare const llmStream: (defaults?: StreamOptions) => Plugin<{}, DeriveDefinitions & {
-    message: {
-        startStream: (opts?: StreamOptions) => MarkdownStreamer;
-        /**
-         * One-call helper for chat completions: consumes a `Response`
-         * (or any `AsyncIterable<LLMChunk>`), renders reasoning to an
-         * expandable blockquote message + content to a streamed markdown
-         * message, returns `{ content, reasoning }` when the stream ends.
-         */
-        startChatStream: (source: Response | AsyncIterable<LLMChunk>, opts?: ChatStreamOptions) => Promise<ChatStreamResult>;
-    };
-}, {}>;
-/**
- * Return shape of `consumeChatStream` / `ctx.startChatStream`. Both
- * full transcripts are returned so the caller decides what to persist
- * (typically `content` to `ctx.llm`; `reasoning` already lives in the
- * Telegram message and is rarely worth storing).
- */
-export type ChatStreamResult = {
-    /** Full assistant text concatenated from all `content` chunks. */
+export interface ChatReplyResult {
+    /** Full assistant markdown, concatenated from `delta` events. */
     content: string;
-    /** Full reasoning text concatenated from all `reasoning` chunks. Empty for non-thinking models. */
+    /** Full reasoning text. Empty for non-thinking models. */
     reasoning: string;
-};
-export type ChatStreamOptions = StreamOptions;
+    /** Tool calls the model made (the caller executes them; nothing is rendered). */
+    toolCalls: LlmToolCall[];
+    /** End-of-stream usage accounting, when the provider reported it. */
+    usage: LlmUsage | null;
+    /** The persisted message(s), in order. Empty when the model produced no text (tool-call-only turns). */
+    messages: MessageContext<Bot>[];
+}
 /**
- * One-shot helper that consumes an LLM stream and renders BOTH phases
- * (reasoning, content) to Telegram with the canonical pattern:
- *
- *   - reasoning chunks → one message containing a single
- *     `<blockquote expandable>…</blockquote>` (HTML), debounced edits,
- *     stays expanded after the stream ends so the user can review it
- *     collapsed/uncollapsed at will
- *   - content chunks → a fresh `MarkdownStreamer` message below the
- *     reasoning one (auto-threaded via SendMixin)
- *
- * Returns when the source generator ends. Equivalent to (and replaces)
- * the ~50 LOC of bookkeeping every thinking-model bot would otherwise
- * write by hand around `streamChat` + `ctx.startStream`.
- *
- * Accepts either a raw `fetch` `Response` (wrapped with `streamChat`
- * internally) or an `AsyncIterable<LLMChunk>` (when you want to map /
- * filter chunks before the stream hits Telegram).
- *
- * @example  via ctx.startChatStream from the llmStream plugin
- * const response = await fetch(LLM_URL, { method: 'POST', body })
- * const { content } = await ctx.startChatStream(response)
- * ctx.llm.add({ role: 'assistant', content })
- *
- * @example  standalone, framework-agnostic
- * const { content, reasoning } = await consumeChatStream(ctx, response)
+ * Render an LLM event stream into the chat: live draft previews while
+ * generating, entity-split persisted message(s) when done. See the module doc
+ * for the full contract. Returns the transcript pieces plus the sent messages.
  */
-export declare const consumeChatStream: (ctx: {
-    chat: {
-        id: number;
-    };
-    threadId?: number;
-    bot: MarkdownStreamer["bot"];
-}, source: Response | AsyncIterable<LLMChunk>, opts?: ChatStreamOptions) => Promise<ChatStreamResult>;
+export declare function streamChatReply(ctx: MessageContext<Bot>, events: AsyncIterable<LlmStreamEvent>, opts?: StreamChatReplyOptions): Promise<ChatReplyResult>;
 /**
  * Multimodal content shape from OpenAI's chat-completions spec. Either
  * a plain string or an ordered array of typed parts. Image URLs cover
@@ -269,6 +107,13 @@ export type ChatMessage = {
     /** Unix seconds when added — used for retention pruning. */
     date: number;
 };
+/**
+ * Convert stored history into the AI SDK's `ModelMessage` shape for
+ * `llm.stream({ messages })`. Text and image parts map 1:1; `tool` turns are
+ * dropped (tool plumbing belongs to the current request, not replayed
+ * history); an assistant turn's parts flatten to text.
+ */
+export declare function toModelMessages(history: ReadonlyArray<ChatMessage>): ModelMessage[];
 /** Per-thread shards of `ChatMessage`s, persisted in the session. */
 type ChatRecord = {
     shards: {
@@ -325,7 +170,7 @@ export type LLMHistoryFeature = {
      * thread" button that BOTH wipes `ctx.llm` for the current
      * (user, thread) shard AND calls `deleteForumTopic` to remove the
      * Telegram thread (and all its messages) from the chat. Sibling
-     * threads stay intact. Falls back to Redis-only clear when there is
+     * threads stay intact. Falls back to history-only clear when there is
      * no `threadId` (general/non-threaded chats) or Telegram rejects
      * the deletion (e.g. forum supergroup without admin rights).
      */

package/dist/bot/llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/bot/llm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/bot/llm.ts"],"names":[],"mappings":"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"}