telegram-agent-kit 0.1.0 → 0.2.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,4 +1,4 @@
-import { R as RenderEvent, A as AgentStream } from '../interfaces-BRu3W_FZ.js';
+import { R as RenderEvent, A as AgentStream } from '../interfaces-FQIM1SDq.js';
 import { RunnableConfig } from '@langchain/core/runnables';
 import { createDeepAgent } from 'deepagents';
 
@@ -12,9 +12,11 @@ type StreamAgentInput = {
 declare function streamAgent(agent: Agent$1, input: StreamAgentInput, 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 };

package/dist/deepagents/index.js

@@ -62,14 +62,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-FQIM1SDq.js';
+export { b as AgentStreamContext, R as RenderEvent, S as StreamInput } from './interfaces-FQIM1SDq.js';
 
 type SendOpts = {
     rich: boolean;
@@ -78,6 +78,7 @@ type RunTelegramTurnOpts = {
     };
     makeDraftStreamer?: (deps: DraftStreamerDeps) => DraftStreamer;
     draftConstants?: Partial<DraftConstants>;
+    configurable?: Record<string, unknown>;
 };
 declare function runTelegramTurn(opts: RunTelegramTurnOpts): Promise<void>;
 

package/dist/index.js

@@ -731,7 +731,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-FQIM1SDq.d.ts}

@@ -67,6 +67,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.2.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",