@adriangalilea/utils 0.12.0 → 0.14.0

package/README.md

@@ -198,7 +198,7 @@ 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-stream` (streaming LLM markdown to Telegram with graceful degradation)
+- **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`), `coalesce`, `language`, `menu`
 
 ### XDG Base Directories
 
@@ -305,7 +305,8 @@ Then `pnpm install`. Every `ctx.send` / `ctx.sendDocument` / `ctx.reply` / etc.
 | `@adriangalilea/utils/bot/kit` | `gracefulStart(bot)` — SIGINT/SIGTERM → `bot.stop()` → exit; force-kills if shutdown hangs.<br>`adminContext({ adminId? })` — reads `TELEGRAM_ADMIN_ID` from `kev` (with optional hardcoded fallback), decorates `ctx.adminId` + `ctx.isAdmin`. |
 | `@adriangalilea/utils/bot/access-control` | Personal-bot ACL — gates non-admin/non-default users; admin gets DM with `[✅ Aprobar][❌ Denegar]` on first attempt; `/access` opens a persistent menu (revoke / reapprove / list pending). Backed by `@gramio/session` per-user + a small index. |
 | `@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-stream` | `ctx.startStream()` for LLM token streams. Debounced `editMessageText`, splits at 4000 chars on paragraph/line/word boundary, parses Markdown locally so malformed mid-stream markup degrades to plain text instead of failing. |
+| `@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 "🧹 Clear this thread" for `botMenu`). |
+| `@adriangalilea/utils/bot/menu` | `botMenu({ command, description, items, privacy?, personalData?, adminContact })` — `/settings` command + InlineKeyboard router. With `personalData: { storage }`, auto-adds 🗑 Forget + 📥 Export buttons. `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. |
 
 Standard wiring:
 
@@ -314,18 +315,37 @@ import { Bot } from 'gramio'
 import { redisStorage } from '@gramio/storage-redis'
 import { adminContext, gracefulStart } from '@adriangalilea/utils/bot/kit'
 import { accessControl } from '@adriangalilea/utils/bot/access-control'
-import { llmStream } from '@adriangalilea/utils/bot/llm-stream'
+import { session } from '@gramio/session'
+import { llmStream, llmHistory } from '@adriangalilea/utils/bot/llm'
 
 const storage = redisStorage()                      // ONE instance, shared
+const userSession = session({ storage, key: 'session', initial: () => ({}) })
+const chat = llmHistory({ session: userSession, maxTurns: 20, retentionDays: 7 })
 
 const bot = new Bot(process.env.BOT_TOKEN!)
   .extend(adminContext({ adminId: 190202471 }))     // KEV.TELEGRAM_ADMIN_ID overrides
-  .extend(accessControl({ storage, defaults: [] })) // gate; depends on adminContext
+  .extend(userSession)
+  .extend(accessControl({ session: userSession, storage, defaults: [] }))
   .extend(llmStream())
-  .command('chat', async (ctx) => {
-    const stream = ctx.startStream()
-    for await (const chunk of yourLLM()) await stream.append(chunk.text)
-    await stream.end()
+  .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)
+    ctx.llm.add({ role: 'assistant', content })
   })
 
 await gracefulStart(bot)

package/dist/bot/access-control.d.ts

@@ -25,7 +25,7 @@
  *     storage[String(userId)] = {
  *       access:   { status, approvedAt, … },   // ← this plugin
  *       language: 'es',                         // ← bot/language
- *       history:  { items: [...] },             // ← bot/message-history
+ *       llm:      { shards: { 'general': [...] } },  // ← bot/llm (history)
  *     }
  *
  * Plus one tiny admin-side index so `/access` can list pending /

package/dist/bot/access-control.js

@@ -25,7 +25,7 @@
  *     storage[String(userId)] = {
  *       access:   { status, approvedAt, … },   // ← this plugin
  *       language: 'es',                         // ← bot/language
- *       history:  { items: [...] },             // ← bot/message-history
+ *       llm:      { shards: { 'general': [...] } },  // ← bot/llm (history)
  *     }
  *
  * Plus one tiny admin-side index so `/access` can list pending /

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-stream'
+ *   import { llmStream } from '@adriangalilea/utils/bot/llm'
  *
  * Or all-in-one (pulls every subpath):
  *   import { ... } from '@adriangalilea/utils/bot'
@@ -14,8 +14,7 @@
 export * from './kit.js';
 export * from './access-control.js';
 export * from './coalesce.js';
-export * from './llm-stream.js';
+export * from './llm.js';
 export * from './menu.js';
 export * from './language.js';
-export * from './message-history.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,UAAU,CAAA;AACxB,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,UAAU,CAAA;AACxB,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

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-stream'
+ *   import { llmStream } from '@adriangalilea/utils/bot/llm'
  *
  * Or all-in-one (pulls every subpath):
  *   import { ... } from '@adriangalilea/utils/bot'
@@ -14,8 +14,7 @@
 export * from './kit.js';
 export * from './access-control.js';
 export * from './coalesce.js';
-export * from './llm-stream.js';
+export * from './llm.js';
 export * from './menu.js';
 export * from './language.js';
-export * from './message-history.js';
 //# sourceMappingURL=index.js.map

package/dist/bot/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,UAAU,CAAA;AACxB,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,UAAU,CAAA;AACxB,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/dist/bot/llm.d.ts

@@ -0,0 +1,520 @@
+/**
+ * GramIO LLM toolkit — three primitives that together form a complete
+ * Telegram LLM-chatbot pipeline:
+ *
+ *   `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.
+ *
+ *   `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:
+ *
+ *     fetch(...) ──streamChat──> chunks ──ctx.startStream──> Telegram
+ *           ▲                                                   │
+ *           └──── ctx.llm.get() ◀──── ctx.llm.add(assistant) ◀──┘
+ *
+ * Peer deps: `gramio`, `@gramio/session`, `@gramio/format`, `marked`.
+ *
+ * @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 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()
+ */
+import { type DeriveDefinitions, Plugin } from 'gramio';
+import { session } from '@gramio/session';
+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;
+    /**
+     * `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')
+     *   }
+     */
+    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;
+}
+/**
+ * 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. */
+    content: string;
+    /** Full reasoning text concatenated from all `reasoning` chunks. Empty for non-thinking models. */
+    reasoning: string;
+};
+export type ChatStreamOptions = StreamOptions;
+/**
+ * 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)
+ */
+export declare const consumeChatStream: (ctx: {
+    chat: {
+        id: number;
+    };
+    threadId?: number;
+    bot: MarkdownStreamer["bot"];
+}, source: Response | AsyncIterable<LLMChunk>, opts?: ChatStreamOptions) => Promise<ChatStreamResult>;
+/**
+ * Multimodal content shape from OpenAI's chat-completions spec. Either
+ * a plain string or an ordered array of typed parts. Image URLs cover
+ * both http(s) and Telegram `getFile` resolved paths.
+ */
+export type ChatContent = string | Array<{
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+}>;
+/**
+ * One turn in the conversation. The library does NOT filter by role —
+ * if you persist `system` turns, they ride along on every `get()`.
+ * Most callers prepend their system prompt fresh each request and only
+ * persist `user` / `assistant`.
+ */
+export type ChatMessage = {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: ChatContent;
+    /** Unix seconds when added — used for retention pruning. */
+    date: number;
+};
+/** Per-thread shards of `ChatMessage`s, persisted in the session. */
+type ChatRecord = {
+    shards: {
+        [threadKey: string]: ChatMessage[];
+    };
+};
+/** Loose session shape — this plugin only touches the `llm` field. */
+type LLMSessionLike = {
+    llm?: ChatRecord;
+};
+/** @internal — kept unexported so it doesn't clash with peers' refs. */
+type LLMSessionPluginRef = ReturnType<typeof session<LLMSessionLike, 'session'>>;
+export type LLMHistoryOptions = {
+    /**
+     * Shared session plugin. This plugin extends it for type flow;
+     * gramio's runtime dedup ensures the session derive runs once.
+     */
+    session: LLMSessionPluginRef;
+    /** Ring buffer cap **per thread**. Oldest entries dropped past this. */
+    maxTurns: number;
+    /** Entries older than this (in days) are dropped on read. */
+    retentionDays: number;
+    /**
+     * Override the labels of the `menuItem` (the "🧹 clear this thread"
+     * button rendered inside a `botMenu`). Defaults are polyglot
+     * literals covering en + es.
+     */
+    menuLabels?: {
+        /** Button label. Default: `{ en: '🧹 Clear this thread', es: '🧹 Limpiar este hilo' }`. */
+        item?: Polyglot<string>;
+        /** Toast shown after a successful clear. Default: `{ en: '🧹 Cleared.', es: '🧹 Limpio.' }`. */
+        cleared?: Polyglot<string>;
+    };
+};
+export type LLMHistoryFeature = {
+    plugin: ReturnType<typeof buildHistoryPlugin>;
+    /**
+     * Drop-in `MenuItem` for `botMenu({ items: [...] })`: a "clear this
+     * thread" button that calls `ctx.llm.clear()` on the current
+     * (user, thread) shard and acknowledges with a toast. Sibling
+     * threads stay intact.
+     */
+    menuItem: MenuItem;
+};
+/**
+ * Methods decorated onto `ctx.llm`. All synchronous — reads/writes the
+ * session record via `@gramio/session`'s Proxy, which auto-persists.
+ *
+ * Thread isolation is automatic: every method operates on the shard
+ * for `ctx.threadId` (or `'general'` when no thread). Different threads
+ * = different conversations, no leakage.
+ */
+export type LLMHistoryApi = {
+    /** Append one message to the CURRENT thread's shard. */
+    add: (message: Omit<ChatMessage, 'date'> & {
+        date?: number;
+    }) => void;
+    /** Pruned snapshot of the CURRENT thread, oldest-first. */
+    get: () => ReadonlyArray<ChatMessage>;
+    /** Wipe the CURRENT thread's shard. */
+    clear: () => void;
+    /**
+     * Full sharded map, pruned. Use for /export or admin views. Keys are
+     * thread ids (or `'general'`) → ordered messages.
+     */
+    all: () => Readonly<{
+        [threadKey: string]: ReadonlyArray<ChatMessage>;
+    }>;
+    /** Wipe ALL threads for this user. */
+    clearAll: () => void;
+};
+type LLMHistoryDerives = {
+    llm: LLMHistoryApi;
+};
+/**
+ * Per-(user, thread) LLM conversation history. Opt-in. Persists in the
+ * shared `@gramio/session` record under `llm`, so 🗑 Forget from
+ * `botMenu` wipes it together with everything else — one record, one
+ * delete, no per-plugin registry.
+ *
+ * @example
+ * const chat = llmHistory({ session: userSession, maxTurns: 20, retentionDays: 7 })
+ * bot.extend(chat.plugin)
+ *    .on('message', (ctx) => {
+ *      ctx.llm.add({ role: 'user', content: ctx.text ?? '' })
+ *      const messages = ctx.llm.get()        // ChatMessage[] for current thread
+ *      // ... call LLM with messages, then:
+ *      ctx.llm.add({ role: 'assistant', content: reply })
+ *    })
+ */
+export declare const llmHistory: (opts: LLMHistoryOptions) => LLMHistoryFeature;
+declare const buildHistoryPlugin: (args: {
+    sessionPlugin: LLMSessionPluginRef;
+    maxTurns: number;
+    retentionDays: number;
+}) => Plugin<{}, DeriveDefinitions & {
+    global: LLMHistoryDerives;
+} & {
+    message: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    channel_post: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    inline_query: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chosen_inline_result: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    callback_query: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    shipping_query: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    pre_checkout_query: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    poll_answer: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chat_join_request: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_members: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_title: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_photo: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    delete_chat_photo: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    group_chat_created: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    message_auto_delete_timer_changed: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    migrate_to_chat_id: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    migrate_from_chat_id: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    pinned_message: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    invoice: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    successful_payment: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chat_shared: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    proximity_alert_triggered: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_scheduled: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_started: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_ended: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_participants_invited: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    web_app_data: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    location: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    passport_data: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+} & {
+    message: LLMHistoryDerives;
+    callback_query: LLMHistoryDerives;
+}, {}>;
+export {};
+//# sourceMappingURL=llm.d.ts.map

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

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