roboport 0.0.1 → 0.2.0

package/README.md

@@ -8,8 +8,9 @@ Minimal TypeScript framework for building LLM agents.
 bun add roboport zod
 ```
 
-`zod` is a peer dependency, declare it in your own dependencies when you define
-Zod-backed tools.
+`roboport` is built for and tested on [Bun](https://bun.sh) and uses Bun-native
+APIs. `zod` is a required peer dependency — it is imported at runtime, so
+install it alongside the package.
 
 ## Exports
 

package/core/agent.d.ts

@@ -25,11 +25,12 @@ declare class Agent {
     on<T>(trigger: Trigger<T>, handler: TriggerHandler<T>): void;
     start(): Promise<void>;
     stop(): Promise<void>;
-    buildSystem(allTools: Tool[]): string;
+    buildSystem(allTools: Tool[], systemExtension?: string): string;
     private buildSkillTool;
     session(init?: {
         messages?: Message[];
         cwd?: string;
+        systemExtension?: string;
     }): Session;
 }
 export { Agent };

package/gateways/core.d.ts

@@ -0,0 +1,27 @@
+import type { Turn } from '../core';
+import type { MaybePromise, Unsub } from '../triggers/core';
+interface InboundMessage {
+    id: string;
+    conversationId: string;
+    text: string;
+    user?: {
+        id: string;
+        name?: string;
+    };
+    replyToId?: string;
+    raw?: unknown;
+}
+interface Channel {
+    conversationId: string;
+    send(text: string): Promise<void>;
+    thinking?(): () => void;
+}
+type GatewayHandler<In extends InboundMessage, Ch extends Channel> = (message: In, channel: Ch) => MaybePromise<void>;
+type Relay<In extends InboundMessage, Ch extends Channel> = (turn: Turn, channel: Ch, message: In) => Promise<void>;
+interface Gateway<In extends InboundMessage = InboundMessage, Ch extends Channel = Channel> {
+    name: string;
+    open(handler: GatewayHandler<In, Ch>): MaybePromise<Unsub>;
+    handle?(req: Request): Promise<Response>;
+    relay?: Relay<In, Ch>;
+}
+export type { Channel, Gateway, GatewayHandler, InboundMessage, Relay };

package/gateways/index.d.ts

@@ -0,0 +1,5 @@
+import { type Channel, type Gateway, type GatewayHandler, type InboundMessage, type Relay } from './core';
+import { serve, type GatewayRuntime, type ServeOptions } from './serve';
+import { stream, telegramGateway, type TelegramChannel, type TelegramGateway, type TelegramGatewayOptions, type TelegramTransport } from './sources/telegram';
+import { fileStore, memoryStore, type ConversationStore } from './store';
+export { fileStore, memoryStore, serve, stream, telegramGateway, type Channel, type ConversationStore, type Gateway, type GatewayHandler, type GatewayRuntime, type InboundMessage, type Relay, type ServeOptions, type TelegramChannel, type TelegramGateway, type TelegramGatewayOptions, type TelegramTransport, };

package/gateways/index.js

@@ -0,0 +1,575 @@
+// @bun
+// src/gateways/store.ts
+import { createHash } from "crypto";
+import { appendFile, mkdir, readFile } from "fs/promises";
+import { join } from "path";
+function memoryStore() {
+  const byId = new Map;
+  return {
+    load(id) {
+      const existing = byId.get(id);
+      return existing ? [...existing] : null;
+    },
+    append(id, ...messages) {
+      const existing = byId.get(id);
+      if (existing)
+        existing.push(...messages);
+      else
+        byId.set(id, [...messages]);
+    }
+  };
+}
+function fileNameFor(id) {
+  const prefix = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+  const hash = createHash("sha256").update(id).digest("hex").slice(0, 16);
+  return `${prefix}-${hash}.jsonl`;
+}
+function fileStore(dir) {
+  function fileFor(id) {
+    return join(dir, fileNameFor(id));
+  }
+  return {
+    async load(id) {
+      let raw;
+      try {
+        raw = await readFile(fileFor(id), "utf8");
+      } catch {
+        return null;
+      }
+      const messages = [];
+      for (const line of raw.split(`
+`)) {
+        if (!line.trim())
+          continue;
+        try {
+          messages.push(JSON.parse(line));
+        } catch {}
+      }
+      return messages;
+    },
+    async append(id, ...messages) {
+      if (messages.length === 0)
+        return;
+      await mkdir(dir, { recursive: true });
+      const lines = messages.map((message) => JSON.stringify(message)).join(`
+`);
+      await appendFile(fileFor(id), `${lines}
+`, "utf8");
+    }
+  };
+}
+
+// src/gateways/serve.ts
+function toUserMessage(prompt) {
+  return { role: "user", content: prompt };
+}
+function newMessages(session, seedLength) {
+  const all = session.messages;
+  const head = all[0]?.role === "system" ? 1 : 0;
+  return [...all.slice(head + seedLength + 1)];
+}
+async function bufferReplies(turn, channel) {
+  const blocks = [];
+  let failure = null;
+  for await (const event of turn) {
+    if (event.type === "text")
+      blocks.push(event.text);
+    else if (event.type === "error")
+      failure = event.error;
+  }
+  const reply = blocks.join(`
+
+`).trim();
+  if (failure && !reply)
+    throw failure;
+  await channel.send(reply || "(no response)");
+}
+async function defaultError(error, channel) {
+  console.error("[gateways] turn failed:", error);
+  await channel.send("Sorry \u2014 something went wrong.").catch(() => {});
+}
+function serve(agent, gateway, options = {}) {
+  const store = options.store ?? memoryStore();
+  const keyOf = options.conversation ?? ((message) => message.conversationId);
+  const relay = options.relay ?? gateway.relay ?? bufferReplies;
+  const queues = new Map;
+  async function runTurn(message, channel, id) {
+    let stopThinking;
+    try {
+      if (options.authorize && !await options.authorize(message, channel)) {
+        return;
+      }
+      const promptValue = options.prompt ? options.prompt(message) : message.text;
+      if (promptValue === null)
+        return;
+      const stored = await store.load(id) ?? [];
+      const seed = options.context ? await options.context(stored, message) : stored;
+      const seedLength = seed.length;
+      const systemExtension = options.systemExtension ? await options.systemExtension(message) : undefined;
+      const session = agent.session({ messages: seed, systemExtension });
+      await store.append(id, toUserMessage(promptValue));
+      stopThinking = channel.thinking?.();
+      try {
+        const turn = session.send(promptValue);
+        await relay(turn, channel, message);
+        stopThinking?.();
+        stopThinking = undefined;
+        await store.append(id, ...newMessages(session, seedLength));
+      } finally {
+        await session.close();
+      }
+    } catch (error) {
+      stopThinking?.();
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (options.onError)
+        await options.onError(err, channel, message);
+      else
+        await defaultError(err, channel);
+    }
+  }
+  function handler(message, channel) {
+    const id = keyOf(message);
+    const prior = queues.get(id) ?? Promise.resolve();
+    const next = prior.then(() => runTurn(message, channel, id)).catch((error) => {
+      console.error(`[gateways] ${gateway.name} ${id}:`, error);
+    });
+    queues.set(id, next);
+    next.finally(() => {
+      if (queues.get(id) === next)
+        queues.delete(id);
+    });
+  }
+  const opened = Promise.resolve(gateway.open(handler));
+  opened.catch((error) => {
+    console.error(`[gateways] ${gateway.name} failed to open:`, error);
+  });
+  function notWebhook() {
+    return Promise.resolve(new Response("gateway is not in webhook mode", { status: 404 }));
+  }
+  return {
+    async stop() {
+      const unsub = await opened.catch(() => {
+        return;
+      });
+      if (unsub)
+        await unsub();
+    },
+    handle: gateway.handle ? (req) => gateway.handle(req) : notWebhook
+  };
+}
+
+// src/triggers/bus.ts
+function makeBus() {
+  return { subs: new Set };
+}
+function subscribe(bus, emit, filter) {
+  const wrapped = filter ? (event) => {
+    if (filter(event))
+      emit(event);
+  } : emit;
+  bus.subs.add(wrapped);
+  return () => {
+    bus.subs.delete(wrapped);
+  };
+}
+function dispatch(bus, event) {
+  for (const sub of bus.subs)
+    sub(event);
+}
+
+// src/triggers/sources/telegram.ts
+var DEFAULT_UPDATE_CACHE_SIZE = 1024;
+var TELEGRAM_API_BASE = "https://api.telegram.org";
+var MAX_MESSAGE_LENGTH = 4096;
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let diff = 0;
+  for (let i = 0;i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+class UpdateCache {
+  seen = new Set;
+  order = [];
+  maxSize;
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  has(id) {
+    return this.seen.has(id);
+  }
+  add(id) {
+    if (this.seen.has(id))
+      return;
+    this.seen.add(id);
+    this.order.push(id);
+    while (this.order.length > this.maxSize) {
+      const dropped = this.order.shift();
+      if (dropped !== undefined)
+        this.seen.delete(dropped);
+    }
+  }
+}
+function matchesCommand(message, commands, botUsername) {
+  const text = message.text;
+  if (!text || !text.startsWith("/"))
+    return false;
+  const token = text.slice(1).split(/\s/, 1)[0] ?? "";
+  const [name, target] = token.split("@");
+  if (target && botUsername) {
+    const normalized = botUsername.replace(/^@/, "").toLowerCase();
+    if (target.toLowerCase() !== normalized)
+      return false;
+  }
+  return commands.some((command) => (command.startsWith("/") ? command.slice(1) : command) === name);
+}
+
+class TelegramReceiver {
+  messageBus = makeBus();
+  editedMessageBus = makeBus();
+  secretToken;
+  updates;
+  constructor(options) {
+    if (!options.secretToken) {
+      throw new Error("TelegramReceiver requires a non-empty secretToken");
+    }
+    this.secretToken = options.secretToken;
+    this.updates = new UpdateCache(options.updateCacheSize ?? DEFAULT_UPDATE_CACHE_SIZE);
+  }
+  message(opts) {
+    const bus = this.messageBus;
+    const commands = opts?.commands;
+    const botUsername = opts?.botUsername;
+    return {
+      name: "telegram:message",
+      start: (emit) => subscribe(bus, emit, commands ? (m) => matchesCommand(m, commands, botUsername) : undefined)
+    };
+  }
+  editedMessage() {
+    const bus = this.editedMessageBus;
+    return {
+      name: "telegram:edited_message",
+      start: (emit) => subscribe(bus, emit)
+    };
+  }
+  handle = async (req) => {
+    const provided = req.headers.get("x-telegram-bot-api-secret-token");
+    if (!provided || !timingSafeEqual(provided, this.secretToken)) {
+      return new Response("invalid secret token", { status: 401 });
+    }
+    let update;
+    try {
+      update = await req.json();
+    } catch {
+      return new Response("invalid json", { status: 400 });
+    }
+    if (typeof update.update_id !== "number") {
+      return new Response("missing update_id", { status: 400 });
+    }
+    if (this.updates.has(update.update_id)) {
+      return new Response("duplicate", { status: 200 });
+    }
+    if (update.message) {
+      dispatch(this.messageBus, update.message);
+    } else if (update.edited_message) {
+      dispatch(this.editedMessageBus, update.edited_message);
+    }
+    this.updates.add(update.update_id);
+    return new Response("ok", { status: 200 });
+  };
+}
+function splitMessage(text, max = MAX_MESSAGE_LENGTH) {
+  if (max < 1)
+    throw new Error("splitMessage requires max >= 1");
+  if (text.length <= max)
+    return [text];
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > max) {
+    let cut = remaining.lastIndexOf(`
+`, max);
+    if (cut <= 0) {
+      cut = max;
+      const code = remaining.charCodeAt(cut - 1);
+      if (code >= 55296 && code <= 56319)
+        cut -= 1;
+    }
+    chunks.push(remaining.slice(0, cut));
+    remaining = remaining.slice(cut).replace(/^\n/, "");
+  }
+  if (remaining.length > 0)
+    chunks.push(remaining);
+  return chunks;
+}
+
+class TelegramClient {
+  token;
+  baseUrl;
+  constructor(token, opts) {
+    if (!token)
+      throw new Error("TelegramClient requires a bot token");
+    this.token = token;
+    this.baseUrl = (opts?.baseUrl ?? TELEGRAM_API_BASE).replace(/\/+$/, "");
+  }
+  async call(method, params, signal) {
+    const response = await fetch(`${this.baseUrl}/bot${this.token}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(params),
+      ...signal ? { signal } : {}
+    });
+    const data = await response.json();
+    if (!data.ok) {
+      throw new Error(`Telegram ${method} failed (${response.status}): ${data.description ?? "unknown error"}`);
+    }
+    return data.result;
+  }
+  getMe() {
+    return this.call("getMe", {});
+  }
+  sendChatAction(chatId, action = "typing") {
+    return this.call("sendChatAction", { chat_id: chatId, action });
+  }
+  async sendMessage(chatId, text, opts) {
+    if (opts?.parseMode && text.length > MAX_MESSAGE_LENGTH) {
+      throw new Error(`sendMessage: text exceeds ${MAX_MESSAGE_LENGTH} chars with parse_mode ${opts.parseMode}; auto-splitting could break entities. Split it yourself.`);
+    }
+    const sent = [];
+    for (const chunk of splitMessage(text)) {
+      sent.push(await this.call("sendMessage", {
+        chat_id: chatId,
+        text: chunk,
+        ...opts?.parseMode ? { parse_mode: opts.parseMode } : {},
+        ...opts?.messageThreadId !== undefined ? { message_thread_id: opts.messageThreadId } : {},
+        ...opts?.replyToMessageId ? { reply_parameters: { message_id: opts.replyToMessageId } } : {},
+        ...opts?.disableNotification ? { disable_notification: true } : {},
+        ...opts?.linkPreview === false ? { link_preview_options: { is_disabled: true } } : {}
+      }));
+    }
+    return sent;
+  }
+  editMessageText(chatId, messageId, text, opts) {
+    return this.call("editMessageText", {
+      chat_id: chatId,
+      message_id: messageId,
+      text,
+      ...opts?.parseMode ? { parse_mode: opts.parseMode } : {}
+    });
+  }
+  async sendMessageDraft(chatId, draftId, text, opts) {
+    if (!Number.isInteger(draftId) || draftId === 0) {
+      throw new Error("sendMessageDraft: draftId must be a non-zero integer");
+    }
+    if (text.length > MAX_MESSAGE_LENGTH) {
+      throw new Error(`sendMessageDraft: text exceeds ${MAX_MESSAGE_LENGTH} chars; a draft is a single bubble and can't be split. Truncate it and persist the full reply via sendMessage.`);
+    }
+    return this.call("sendMessageDraft", {
+      chat_id: chatId,
+      draft_id: draftId,
+      text,
+      ...opts?.parseMode ? { parse_mode: opts.parseMode } : {},
+      ...opts?.messageThreadId !== undefined ? { message_thread_id: opts.messageThreadId } : {}
+    });
+  }
+  setWebhook(url, opts) {
+    return this.call("setWebhook", {
+      url,
+      ...opts?.secretToken ? { secret_token: opts.secretToken } : {},
+      ...opts?.allowedUpdates ? { allowed_updates: opts.allowedUpdates } : {}
+    });
+  }
+  deleteWebhook(opts) {
+    return this.call("deleteWebhook", {
+      ...opts?.dropPendingUpdates ? { drop_pending_updates: true } : {}
+    });
+  }
+  getUpdates(opts) {
+    return this.call("getUpdates", {
+      ...opts?.offset !== undefined ? { offset: opts.offset } : {},
+      ...opts?.timeout !== undefined ? { timeout: opts.timeout } : {},
+      ...opts?.allowedUpdates ? { allowed_updates: opts.allowedUpdates } : {}
+    }, opts?.signal);
+  }
+}
+function telegram(options) {
+  return new TelegramReceiver(options);
+}
+
+// src/gateways/sources/telegram.ts
+var TYPING_INTERVAL_MS = 4000;
+var POLL_TIMEOUT_SECONDS = 25;
+var POLL_BACKOFF_MS = 1000;
+var DRAFT_THROTTLE_MS = 500;
+var DRAFT_MAX_LENGTH = 4096;
+function conversationKey(message) {
+  return message.message_thread_id !== undefined ? `${message.chat.id}:${message.message_thread_id}` : String(message.chat.id);
+}
+function toInbound(message) {
+  return {
+    id: String(message.message_id),
+    conversationId: conversationKey(message),
+    text: message.text ?? message.caption ?? "",
+    user: message.from ? {
+      id: String(message.from.id),
+      name: message.from.username ?? message.from.first_name
+    } : undefined,
+    replyToId: message.reply_to_message ? String(message.reply_to_message.message_id) : undefined,
+    raw: message
+  };
+}
+function startTyping(client, chatId) {
+  let stopped = false;
+  function tick() {
+    if (!stopped)
+      client.sendChatAction(chatId, "typing").catch(() => {});
+  }
+  tick();
+  const interval = setInterval(tick, TYPING_INTERVAL_MS);
+  return () => {
+    stopped = true;
+    clearInterval(interval);
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function telegramGateway(options) {
+  const client = new TelegramClient(options.token);
+  const transport = options.transport ?? { mode: "polling" };
+  function channelFor(message) {
+    const chatId = message.chat.id;
+    const threadId = message.message_thread_id;
+    return {
+      conversationId: conversationKey(message),
+      chatId,
+      client,
+      send: async (text, opts) => {
+        await client.sendMessage(chatId, text, {
+          messageThreadId: threadId,
+          ...opts
+        });
+      },
+      draft: async (text) => {
+        await client.sendMessageDraft(chatId, message.message_id, text, {
+          messageThreadId: threadId
+        });
+      },
+      thinking: () => startTyping(client, chatId)
+    };
+  }
+  function forwards(message) {
+    return !options.commands || matchesCommand(message, options.commands, options.botUsername);
+  }
+  function deliver(handler, message) {
+    Promise.resolve(handler(toInbound(message), channelFor(message))).catch((error) => {
+      console.error("[gateways] telegram handler error:", error);
+    });
+  }
+  if (transport.mode === "webhook") {
+    const receiver = new TelegramReceiver({
+      secretToken: transport.secretToken
+    });
+    return {
+      name: "telegram",
+      client,
+      handle: receiver.handle,
+      open(handler) {
+        const trigger = receiver.message(options.commands ? { commands: options.commands, botUsername: options.botUsername } : undefined);
+        return trigger.start((message) => deliver(handler, message));
+      }
+    };
+  }
+  return {
+    name: "telegram",
+    client,
+    open(handler) {
+      const controller = new AbortController;
+      (async () => {
+        await client.deleteWebhook().catch(() => {});
+        let offset;
+        while (!controller.signal.aborted) {
+          try {
+            const updates = await client.getUpdates({
+              offset,
+              timeout: POLL_TIMEOUT_SECONDS,
+              allowedUpdates: ["message"],
+              signal: controller.signal
+            });
+            for (const update of updates) {
+              offset = update.update_id + 1;
+              const message = update.message;
+              if (message && forwards(message))
+                deliver(handler, message);
+            }
+          } catch (error) {
+            if (controller.signal.aborted)
+              break;
+            console.error("[gateways] telegram polling error:", error);
+            await sleep(POLL_BACKOFF_MS);
+          }
+        }
+      })();
+      return () => controller.abort();
+    }
+  };
+}
+function stream(options = {}) {
+  const throttleMs = options.throttleMs ?? DRAFT_THROTTLE_MS;
+  return async (turn, channel) => {
+    const blocks = [];
+    let current = "";
+    let failure = null;
+    let inFlight = false;
+    let lastSentAt = 0;
+    let lastSentText = "";
+    function preview() {
+      return [blocks.join(`
+
+`), current].filter((part) => part.length > 0).join(`
+
+`);
+    }
+    function refresh() {
+      const body = preview();
+      if (!body || body === lastSentText || body.length > DRAFT_MAX_LENGTH) {
+        return;
+      }
+      if (inFlight || Date.now() - lastSentAt < throttleMs)
+        return;
+      inFlight = true;
+      lastSentAt = Date.now();
+      lastSentText = body;
+      channel.draft(body).catch(() => {}).finally(() => {
+        inFlight = false;
+      });
+    }
+    for await (const event of turn) {
+      if (event.type === "text-delta") {
+        current += event.text;
+        refresh();
+      } else if (event.type === "text") {
+        blocks.push(event.text);
+        current = "";
+        refresh();
+      } else if (event.type === "error") {
+        failure = event.error;
+      }
+    }
+    const reply = blocks.join(`
+
+`).trim();
+    if (failure && !reply)
+      throw failure;
+    await channel.send(reply || "(no response)");
+  };
+}
+export {
+  telegramGateway,
+  stream,
+  serve,
+  memoryStore,
+  fileStore
+};

package/gateways/serve.d.ts

@@ -0,0 +1,19 @@
+import { Agent, type Message, type TextPart } from '../core';
+import type { Channel, Gateway, InboundMessage, Relay } from './core';
+import { type ConversationStore } from './store';
+interface ServeOptions<In extends InboundMessage, Ch extends Channel> {
+    conversation?: (message: In) => string;
+    authorize?: (message: In, channel: Ch) => boolean | Promise<boolean>;
+    systemExtension?: (message: In) => string | Promise<string>;
+    prompt?: (message: In) => string | TextPart[] | null;
+    context?: (stored: Message[], message: In) => Message[] | Promise<Message[]>;
+    relay?: Relay<In, Ch>;
+    store?: ConversationStore;
+    onError?: (error: Error, channel: Ch, message: In) => void | Promise<void>;
+}
+interface GatewayRuntime {
+    stop(): Promise<void>;
+    handle(req: Request): Promise<Response>;
+}
+declare function serve<In extends InboundMessage, Ch extends Channel>(agent: Agent, gateway: Gateway<In, Ch>, options?: ServeOptions<In, Ch>): GatewayRuntime;
+export { serve, type GatewayRuntime, type ServeOptions };

package/gateways/sources/telegram.d.ts

@@ -0,0 +1,28 @@
+import { TelegramClient, type SendMessageOptions } from '../../triggers/sources/telegram';
+import type { Channel, Gateway, InboundMessage, Relay } from '../core';
+interface TelegramChannel extends Channel {
+    chatId: number;
+    client: TelegramClient;
+    send(text: string, opts?: SendMessageOptions): Promise<void>;
+    draft(text: string): Promise<void>;
+}
+type TelegramTransport = {
+    mode: 'polling';
+} | {
+    mode: 'webhook';
+    secretToken: string;
+};
+interface TelegramGatewayOptions {
+    token: string;
+    transport?: TelegramTransport;
+    commands?: string[];
+    botUsername?: string;
+}
+interface TelegramGateway extends Gateway<InboundMessage, TelegramChannel> {
+    client: TelegramClient;
+}
+declare function telegramGateway(options: TelegramGatewayOptions): TelegramGateway;
+declare function stream(options?: {
+    throttleMs?: number;
+}): Relay<InboundMessage, TelegramChannel>;
+export { stream, telegramGateway, type TelegramChannel, type TelegramGateway, type TelegramGatewayOptions, type TelegramTransport, };

package/gateways/store.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from '../core';
+import type { MaybePromise } from '../triggers/core';
+interface ConversationStore {
+    load(id: string): MaybePromise<Message[] | null>;
+    append(id: string, ...messages: Message[]): MaybePromise<void>;
+}
+declare function memoryStore(): ConversationStore;
+declare function fileStore(dir: string): ConversationStore;
+export { fileStore, memoryStore, type ConversationStore };