telegram-agent-kit 0.1.0 → 0.3.0

package/README.md

@@ -147,7 +147,7 @@ You implement these; the kit drives them.
 | Interface      | Shape                                                                 | Role |
 | -------------- | --------------------------------------------------------------------- | ---- |
 | `BotClient`    | `sendMessage`, `sendRichMessage`, `sendPhoto`, `sendChatAction`, `sendMessageDraft`, `sendRichMessageDraft` | Raw transport. Each throws `TelegramApiError` on a Bot API error. |
-| `AgentStream`  | `(input, { threadId, signal }) => AsyncIterable<RenderEvent>`          | Your agent. `threadId` **must** reach it so the checkpointer writes to the snapshotted thread. |
+| `AgentStream`  | `(input, { threadId, signal, configurable }) => AsyncIterable<RenderEvent>` | Your agent. `threadId` **must** reach it so the checkpointer writes to the snapshotted thread. `configurable` is an optional pass-through bag forwarded verbatim from `runTelegramTurn`'s `configurable` option. |
 | `Checkpointer` | `{ snapshot(threadId), rollback(threadId, id) }`                       | Per-thread snapshot/rollback for clean recovery on a failed turn. |
 | `ThreadStore`  | `{ resolve(chatKey, now), touch(chatKey, now) }`                      | Maps `{ chatId, agentId }` to a thread id (so two bots over one chat id don't collide). |
 
@@ -175,6 +175,8 @@ appends `token` text to the live draft and treats an `error` event as a rollback
 **Bridge**
 
 - `runTelegramTurn(opts)` — orchestrate one turn. Never throws out; every failure is caught and logged.
+  Accepts an optional `configurable` bag forwarded to your `AgentStream` as `context.configurable`,
+  for passing per-turn data (e.g. `pendingImages`) to the agent without widening the core input type.
 - `sendReply(client, chatId, reply, opts, signal?)` / `sendText(...)` — the send path on its own.
 - Types: `BotClient`, `AgentStream`, `Checkpointer`, `ThreadStore`, `RenderEvent`, `ChatKey`, `Logger`.
 
@@ -186,6 +188,10 @@ appends `token` text to the live draft and treats an `error` event as a rollback
 ### Optional entry — `telegram-agent-kit/deepagents`
 
 - `toAgentStream(agent)` → `AgentStream` — adapts a deepagents/langgraph agent to the kit's contract.
+  The `context.configurable` bag is merged into the LangGraph `RunnableConfig`, but the reserved keys
+  `thread_id`, `thread_ts`, `checkpoint_id`, `checkpoint_ns`, `checkpoint_map`, and `run_id` — plus any
+  `__pregel_*` LangGraph internal-execution key — are stripped so the kit retains full control over
+  checkpoint routing and execution.
 - `streamAgent(agent, input, config, signal?)` — lower-level event stream if you need direct control.
 
 > `@langchain/core` and `deepagents` are **type-only, optional** peers. The built

package/dist/deepagents/index.d.ts

@@ -1,20 +1,16 @@
-import { R as RenderEvent, A as AgentStream } from '../interfaces-BRu3W_FZ.js';
+import { S as StreamInput, R as RenderEvent, A as AgentStream } from '../interfaces-DhF4n199.js';
 import { RunnableConfig } from '@langchain/core/runnables';
 import { createDeepAgent } from 'deepagents';
 
 type Agent$1 = ReturnType<typeof createDeepAgent>;
-type StreamAgentInput = {
-    messages: Array<{
-        role: 'user';
-        content: string;
-    }>;
-};
-declare function streamAgent(agent: Agent$1, input: StreamAgentInput, config: RunnableConfig, signal?: AbortSignal): AsyncIterable<RenderEvent>;
+declare function streamAgent(agent: Agent$1, input: StreamInput, config: RunnableConfig, signal?: AbortSignal): AsyncIterable<RenderEvent>;
 
 type Agent = Parameters<typeof streamAgent>[0];
-/** Adapt a deepagents agent to the kit's runtime-agnostic AgentStream: build
- *  the langgraph config from context.threadId, forward the signal. This is the
- *  ONLY place the langgraph config shape lives. */
+/** Adapt a deepagents agent to the kit's runtime-agnostic AgentStream: merge the
+ *  caller's `configurable` bag (with reserved checkpoint-routing keys stripped)
+ *  under the kit-owned `thread_id`, and forward the signal. The kit's `thread_id`
+ *  is spread last so it always wins, even if stripping ever misses a key. This is
+ *  the ONLY place the langgraph config shape lives. */
 declare function toAgentStream(agent: Agent): AgentStream;
 
-export { RenderEvent, type StreamAgentInput, streamAgent, toAgentStream };
+export { RenderEvent, StreamInput, streamAgent, toAgentStream };

package/dist/deepagents/index.js

@@ -8,20 +8,7 @@ function extractText(content) {
   }
   return "";
 }
-function extractToolError(output) {
-  if (typeof output !== "object" || output === null) return void 0;
-  const o = output;
-  if (o.status !== "error") return void 0;
-  const c = o.content;
-  if (typeof c === "string") return c;
-  try {
-    return JSON.stringify(c);
-  } catch {
-    return String(c);
-  }
-}
 async function* streamAgent(agent, input, config, signal) {
-  const toolStart = /* @__PURE__ */ new Map();
   const iter = agent.streamEvents(input, {
     ...config,
     signal,
@@ -33,24 +20,6 @@ async function* streamAgent(agent, input, config, signal) {
         if (ev.metadata?.langgraph_node !== "model_request") continue;
         const text = extractText(ev.data?.chunk?.content);
         if (text) yield { type: "token", text };
-      } else if (ev.event === "on_tool_start") {
-        toolStart.set(ev.run_id, Date.now());
-        yield {
-          type: "tool_start",
-          id: ev.run_id,
-          name: ev.name ?? "unknown",
-          args: ev.data?.input
-        };
-      } else if (ev.event === "on_tool_end" || ev.event === "on_tool_error") {
-        const startedAt = toolStart.get(ev.run_id) ?? Date.now();
-        toolStart.delete(ev.run_id);
-        const error = ev.event === "on_tool_error" ? ev.data?.error instanceof Error ? ev.data.error.message : String(ev.data?.error ?? "tool error") : extractToolError(ev.data?.output);
-        yield {
-          type: "tool_end",
-          id: ev.run_id,
-          durationMs: Date.now() - startedAt,
-          ...error !== void 0 ? { error } : {}
-        };
       }
     }
   } catch (err) {
@@ -62,14 +31,38 @@ async function* streamAgent(agent, input, config, signal) {
 }
 
 // src/deepagents/to-agent-stream.ts
-function toAgentStream(agent) {
-  return (input, context) => streamAgent(
-    agent,
-    input,
-    { configurable: { thread_id: context.threadId } },
-    context.signal
+var RESERVED = /* @__PURE__ */ new Set([
+  "thread_id",
+  // Legacy alias for `checkpoint_id`: the installed @langchain/langgraph-checkpoint
+  // still resolves it via getCheckpointId() (`checkpoint_id || thread_ts`), so a
+  // caller could resume from a hand-picked checkpoint through this key alone even
+  // with `checkpoint_id` stripped. Strip it too.
+  "thread_ts",
+  "checkpoint_id",
+  "checkpoint_ns",
+  "checkpoint_map",
+  "run_id"
+]);
+var RESERVED_PREFIX = "__pregel_";
+function stripReservedKeys(configurable) {
+  return Object.fromEntries(
+    Object.entries(configurable).filter(
+      ([k]) => !RESERVED.has(k) && !k.startsWith(RESERVED_PREFIX)
+    )
   );
 }
+function toAgentStream(agent) {
+  return (input, context) => {
+    const extra = context.configurable ?? {};
+    const safe = stripReservedKeys(extra);
+    return streamAgent(
+      agent,
+      input,
+      { configurable: { ...safe, thread_id: context.threadId } },
+      context.signal
+    );
+  };
+}
 export {
   streamAgent,
   toAgentStream

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BotClient, L as Logger, C as ChatKey, A as AgentStream, a as Checkpointer, T as ThreadStore } from './interfaces-BRu3W_FZ.js';
-export { b as AgentStreamContext, R as RenderEvent, S as StreamInput } from './interfaces-BRu3W_FZ.js';
+import { B as BotClient, L as Logger, C as ChatKey, A as AgentStream, a as Checkpointer, T as ThreadStore } from './interfaces-DhF4n199.js';
+export { b as AgentStreamContext, R as RenderEvent, S as StreamInput } from './interfaces-DhF4n199.js';
 
 type SendOpts = {
     rich: boolean;
@@ -76,8 +76,8 @@ type RunTelegramTurnOpts = {
         beforeTurn?: (ctx: TurnContext) => void | Promise<void>;
         afterTurn?: (ctx: TurnContext) => void | Promise<void>;
     };
-    makeDraftStreamer?: (deps: DraftStreamerDeps) => DraftStreamer;
     draftConstants?: Partial<DraftConstants>;
+    configurable?: Record<string, unknown>;
 };
 declare function runTelegramTurn(opts: RunTelegramTurnOpts): Promise<void>;
 

package/dist/index.js

@@ -170,7 +170,7 @@ function renderLinks(text, autoClose) {
     rest = rest.slice(m.index + m.length);
   }
 }
-function renderCode(text, autoClose) {
+function renderInline(text, autoClose) {
   let out = "";
   let rest = text;
   for (; ; ) {
@@ -193,9 +193,6 @@ function renderCode(text, autoClose) {
     rest = rest.slice(close + 1);
   }
 }
-function renderInline(line, autoClose) {
-  return renderCode(line, autoClose);
-}
 var FENCE_OPEN_RE = /^(`{3,}|~{3,})\s*(.*)$/;
 var TICK_CLOSE_RE = /^`{3,}\s*$/;
 var TILDE_CLOSE_RE = /^~{3,}\s*$/;
@@ -691,7 +688,6 @@ var NOOP_LOG = { warn: () => {
 async function runTelegramTurn(opts) {
   const now = opts.now ?? (() => Date.now());
   const log = opts.log ?? NOOP_LOG;
-  const makeDraftStreamer = opts.makeDraftStreamer ?? createDraftStreamer;
   const ctx = { chatKey: opts.chatKey, userText: opts.userText };
   let rollback = null;
   let turnCompleted = false;
@@ -718,7 +714,7 @@ async function runTelegramTurn(opts) {
     const threadId = await opts.threadStore.resolve(opts.chatKey, now());
     const checkpointId = await opts.checkpointer.snapshot(threadId);
     rollback = { threadId, checkpointId };
-    draft = makeDraftStreamer({
+    draft = createDraftStreamer({
       client: opts.client,
       chatId: opts.chatKey.chatId,
       draftId: opts.draftId,
@@ -731,7 +727,7 @@ async function runTelegramTurn(opts) {
     let errored = false;
     for await (const ev of opts.agentStream(
       { messages: [{ role: "user", content: opts.userText }] },
-      { threadId, signal: opts.signal }
+      { threadId, signal: opts.signal, configurable: opts.configurable }
     )) {
       if (ev.type === "token") {
         reply += ev.text;

package/dist/{interfaces-BRu3W_FZ.d.ts → interfaces-DhF4n199.d.ts}

@@ -5,7 +5,6 @@ type ChatKey = {
 type Logger = {
     warn(msg: string, data?: unknown): void;
     error(msg: string, data?: unknown): void;
-    info?(msg: string, data?: unknown): void;
 };
 /** Raw Bot API transport primitives — one HTTP call each, NO chunking /
  *  rendering / fallback (the kit owns those). Each throws TelegramApiError
@@ -44,16 +43,6 @@ type BotClient = {
 type RenderEvent = {
     type: 'token';
     text: string;
-} | {
-    type: 'tool_start';
-    id: string;
-    name: string;
-    args: unknown;
-} | {
-    type: 'tool_end';
-    id: string;
-    durationMs: number;
-    error?: string;
 } | {
     type: 'error';
     message: string;
@@ -67,6 +56,7 @@ type StreamInput = {
 type AgentStreamContext = {
     threadId: string;
     signal?: AbortSignal;
+    configurable?: Record<string, unknown>;
 };
 type AgentStream = (input: StreamInput, context: AgentStreamContext) => AsyncIterable<RenderEvent>;
 type Checkpointer = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-agent-kit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Render markdown to Telegram, stream agent replies into live drafts, and drive a snapshot/rollback turn-loop — runtime-agnostic.",
   "type": "module",
   "license": "MIT",