ompclaw 0.3.0

package/src/gateway-types.ts

@@ -0,0 +1,290 @@
+export interface TransportIdentity {
+  readonly transport: string;
+  readonly account: string;
+  readonly subject: string;
+}
+
+export interface Principal {
+  readonly id: string;
+  readonly roles: readonly string[];
+}
+
+export interface ConversationAddress {
+  readonly transport: string;
+  readonly account: string;
+  readonly channel: string;
+  readonly thread?: string;
+}
+export interface DeliveryContext {
+  readonly principal: Principal;
+  readonly origin: ConversationAddress;
+}
+
+
+export interface MessageAttachment {
+  readonly url: string;
+  readonly name?: string;
+  readonly mediaType?: string;
+}
+
+export interface InboundContent {
+  readonly text?: string;
+  readonly attachments?: readonly MessageAttachment[];
+}
+
+/**
+ * Transport-provided data. A principal is deliberately absent: it is derived by
+ * the gateway from identity before any inbound handler can observe the message.
+ */
+export interface InboundEnvelope {
+  readonly id: string;
+  readonly sentAt: number;
+  readonly identity: TransportIdentity;
+  readonly address: ConversationAddress;
+  readonly content: InboundContent;
+  readonly replyTo?: OutboundReceipt;
+  readonly edited?: boolean;
+}
+
+export interface InboundMessage extends InboundEnvelope {
+  readonly principal: Principal;
+}
+
+export interface OutboundContent {
+  readonly text?: string;
+  readonly attachments?: readonly MessageAttachment[];
+  readonly replyTo?: OutboundReceipt;
+  readonly format?: "text" | "markdown";
+}
+
+/** A transport-native message identifier paired with its issuing transport. */
+export interface OutboundReceipt {
+  readonly transport: string;
+  readonly messageId: string;
+}
+
+export interface Reaction {
+  readonly emoji: string;
+}
+
+export type TransportCapability =
+  | "streamingUpdates"
+  | "buttons"
+  | "multiSelect"
+  | "textInput"
+  | "attachments"
+  | "reactions"
+  | "threads";
+
+export interface TransportCapabilities {
+  readonly streamingUpdates: boolean;
+  readonly buttons: boolean;
+  readonly multiSelect: boolean;
+  readonly textInput: boolean;
+  readonly attachments: boolean;
+  readonly reactions: boolean;
+  readonly threads: boolean;
+  readonly maxMessageLength: number;
+}
+
+export interface UiOption {
+  readonly value: string;
+  readonly label: string;
+  readonly description?: string;
+}
+
+export interface ConfirmUiRequest {
+  readonly type: "confirm";
+  readonly title: string;
+  readonly message: string;
+  readonly confirmLabel?: string;
+  readonly cancelLabel?: string;
+}
+
+export interface SelectUiRequest {
+  readonly type: "select";
+  readonly title: string;
+  readonly options: readonly UiOption[];
+  readonly multiSelect?: boolean;
+}
+
+export interface InputUiRequest {
+  readonly type: "input";
+  readonly title: string;
+  readonly prompt?: string;
+  readonly initialValue?: string;
+  readonly placeholder?: string;
+}
+
+export interface EditorUiRequest {
+  readonly type: "editor";
+  readonly title: string;
+  readonly initialValue: string;
+  readonly language?: string;
+}
+
+export interface NotifyUiRequest {
+  readonly type: "notify";
+  readonly message: string;
+  readonly level?: "info" | "success" | "warning" | "error";
+}
+
+export interface OpenUrlUiRequest {
+  readonly type: "open_url";
+  readonly url: string;
+  readonly label?: string;
+}
+export interface StatusUiRequest {
+  readonly type: "status";
+  readonly key: string;
+  readonly text?: string;
+}
+
+export interface WidgetUiRequest {
+  readonly type: "widget";
+  readonly key: string;
+  readonly lines?: readonly string[];
+  readonly placement?: "aboveEditor" | "belowEditor";
+}
+
+export interface TitleUiRequest {
+  readonly type: "title";
+  readonly title: string;
+}
+
+export interface EditorTextUiRequest {
+  readonly type: "editor_text";
+  readonly text: string;
+}
+
+
+export type UiRequest =
+  | ConfirmUiRequest
+  | SelectUiRequest
+  | InputUiRequest
+  | EditorUiRequest
+  | NotifyUiRequest
+  | OpenUrlUiRequest
+  | StatusUiRequest
+  | WidgetUiRequest
+  | TitleUiRequest
+  | EditorTextUiRequest;
+
+export interface ConfirmUiResponse {
+  readonly type: "confirm";
+  readonly confirmed: boolean;
+}
+
+export interface SelectUiResponse {
+  readonly type: "select";
+  readonly selected: readonly string[];
+}
+
+export type InputUiResponse =
+  | { readonly type: "input"; readonly cancelled: true }
+  | { readonly type: "input"; readonly cancelled: false; readonly value: string };
+
+export type EditorUiResponse =
+  | { readonly type: "editor"; readonly cancelled: true }
+  | { readonly type: "editor"; readonly cancelled: false; readonly value: string };
+
+export interface NotifyUiResponse {
+  readonly type: "notify";
+  readonly acknowledged: true;
+}
+
+export interface OpenUrlUiResponse {
+  readonly type: "open_url";
+  readonly opened: boolean;
+}
+export interface StatusUiResponse {
+  readonly type: "status";
+  readonly acknowledged: true;
+}
+
+export interface WidgetUiResponse {
+  readonly type: "widget";
+  readonly acknowledged: true;
+}
+
+export interface TitleUiResponse {
+  readonly type: "title";
+  readonly acknowledged: true;
+}
+
+export interface EditorTextUiResponse {
+  readonly type: "editor_text";
+  readonly acknowledged: true;
+}
+
+
+export type UiResponse =
+  | ConfirmUiResponse
+  | SelectUiResponse
+  | InputUiResponse
+  | EditorUiResponse
+  | NotifyUiResponse
+  | OpenUrlUiResponse
+  | StatusUiResponse
+  | WidgetUiResponse
+  | TitleUiResponse
+  | EditorTextUiResponse;
+
+export type UiResponseFor<Request extends UiRequest> = Extract<UiResponse, { readonly type: Request["type"] }>;
+
+export type ReceiveInbound = (envelope: InboundEnvelope, signal?: AbortSignal) => Promise<void>;
+
+export type ResolveTransportIdentity = (
+  identity: TransportIdentity,
+  signal?: AbortSignal,
+) => Principal | undefined | Promise<Principal | undefined>;
+
+export interface TransportStartContext {
+  readonly receive: ReceiveInbound;
+  readonly resolveIdentity: ResolveTransportIdentity;
+  readonly signal?: AbortSignal;
+}
+
+export interface TransportAdapter {
+  readonly id: string;
+  readonly capabilities: TransportCapabilities;
+  start(context: TransportStartContext): void | Promise<void>;
+  stop(): void | Promise<void>;
+  send(
+    address: ConversationAddress,
+    content: OutboundContent,
+    context: DeliveryContext,
+    signal?: AbortSignal,
+  ): Promise<OutboundReceipt>;
+  update?(
+    address: ConversationAddress,
+    receipt: OutboundReceipt,
+    content: OutboundContent,
+    context: DeliveryContext,
+    signal?: AbortSignal,
+  ): Promise<OutboundReceipt>;
+  react?(
+    address: ConversationAddress,
+    receipt: OutboundReceipt,
+    reaction: Reaction,
+    context: DeliveryContext,
+    signal?: AbortSignal,
+  ): Promise<void>;
+  presentUi?<Request extends UiRequest>(
+    address: ConversationAddress,
+    request: Request,
+    context: DeliveryContext,
+    signal?: AbortSignal,
+  ): Promise<UiResponseFor<Request>>;
+}
+
+export class UnsupportedTransportCapabilityError extends Error {
+  readonly name = "UnsupportedTransportCapabilityError";
+
+  constructor(
+    readonly transport: string,
+    readonly capability: TransportCapability,
+  ) {
+    super(`Transport ${transport} does not support ${capability}`);
+  }
+}

package/src/inbox.ts

@@ -0,0 +1,77 @@
+import { mkdir, readdir, stat, unlink, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+export const INBOX_MAX_FILE_BYTES = 20 * 1024 * 1024;
+export const INBOX_MAX_TOTAL_BYTES = 250 * 1024 * 1024;
+export const INBOX_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+type InboxFile = { path: string; size: number; mtimeMs: number };
+
+export interface PruneInboxOptions {
+  now?: number;
+  maxTotalBytes?: number;
+  retentionMs?: number;
+  preserve?: ReadonlySet<string>;
+}
+
+/** Remove expired files, then oldest files until the inbox fits its total quota. */
+export async function pruneInbox(dir: string, options: PruneInboxOptions = {}): Promise<{ totalBytes: number; removed: string[] }> {
+  const now = options.now ?? Date.now();
+  const maxTotalBytes = options.maxTotalBytes ?? INBOX_MAX_TOTAL_BYTES;
+  const retentionMs = options.retentionMs ?? INBOX_RETENTION_MS;
+  const preserve = new Set([...(options.preserve ?? [])].map((path) => resolve(path)));
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+
+  const files: InboxFile[] = [];
+  for (const name of await readdir(dir)) {
+    const path = join(dir, name);
+    let info;
+    try {
+      info = await stat(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw error;
+    }
+    if (info.isFile()) files.push({ path, size: info.size, mtimeMs: info.mtimeMs });
+  }
+
+  files.sort((a, b) => a.mtimeMs - b.mtimeMs || a.path.localeCompare(b.path));
+  const removed: string[] = [];
+  let totalBytes = files.reduce((total, file) => total + file.size, 0);
+
+  for (const file of files) {
+    if (preserve.has(resolve(file.path))) continue;
+    const expired = now - file.mtimeMs > retentionMs;
+    if (!expired && totalBytes <= maxTotalBytes) continue;
+    try {
+      await unlink(file.path);
+      totalBytes -= file.size;
+      removed.push(file.path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      totalBytes -= file.size;
+    }
+  }
+
+  return { totalBytes, removed };
+}
+
+/** Persist one bounded attachment with private permissions and enforce inbox quota. */
+export async function storeInboxFile(dir: string, filename: string, bytes: Uint8Array): Promise<string> {
+  if (bytes.byteLength > INBOX_MAX_FILE_BYTES) {
+    throw new Error(`Telegram attachment is too large (${bytes.byteLength} bytes, max ${INBOX_MAX_FILE_BYTES})`);
+  }
+  await pruneInbox(dir);
+  const path = join(dir, filename);
+  await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
+  try {
+    const result = await pruneInbox(dir, { preserve: new Set([path]) });
+    if (result.totalBytes > INBOX_MAX_TOTAL_BYTES) {
+      throw new Error(`Telegram inbox quota exceeded (${result.totalBytes} bytes, max ${INBOX_MAX_TOTAL_BYTES})`);
+    }
+    return path;
+  } catch (error) {
+    await unlink(path).catch(() => undefined);
+    throw error;
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./gateway-types";
+export * from "./gateway-core";
+export * from "./gateway-store";
+export * from "./gateway-tools";
+export * from "./gateway-config";
+export * from "./gateway-app";
+export * from "./rpc-protocol";
+export * from "./rpc-client";
+export * from "./rpc-runtime";
+export * from "./rpc-ui";
+export * from "./transports/telegram/adapter";
+export * from "./transports/websocket/adapter";
+export * from "./transports/websocket/protocol";

package/src/markdown.ts

@@ -0,0 +1,156 @@
+// Markdown → Telegram MarkdownV2 conversion and message chunking.
+//
+// Telegram caps a message at 4096 characters counted in UTF-16 code units,
+// which is exactly what JavaScript's `String.length` returns — so `.length` is
+// the correct measure throughout (a non-BMP emoji counts as 2, matching
+// Telegram). Callers always fall back to plain text when Telegram rejects a
+// MarkdownV2 parse (HTTP 400 "can't parse entities"), so a *lossy* conversion is
+// acceptable here; a thrown exception is not — `mdToMarkdownV2` never throws.
+
+/** Telegram's hard per-message character cap (UTF-16 units). */
+export const TELEGRAM_MAX_CHARS = 4096;
+/** Headroom to reserve when a chunk will be MarkdownV2-escaped (escaping grows text). */
+export const MARKDOWN_HEADROOM = 96;
+
+/** Escape every MarkdownV2 special character with a backslash. */
+export function escapeMdV2(s: string): string {
+  return s.replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, "\\$&");
+}
+
+/** Inline formatting for a single line: code/links/bold/italic preserved, the rest escaped. */
+function inlineFormat(s: string): string {
+  const stash: string[] = [];
+  // Protect already-rendered MarkdownV2 fragments behind private-use sentinels so
+  // the final escape pass leaves them untouched. 4 call sites, lockstep protocol.
+  const put = (rendered: string): string => `\uE000${stash.push(rendered) - 1}\uE001`;
+
+  let t = s;
+  // Inline code — inside a code span only ` and \ are special.
+  t = t.replace(/`([^`\n]+)`/g, (_m, code: string) => put("`" + code.replace(/[`\\]/g, "\\$&") + "`"));
+  // Links [text](url) — escape text as normal, escape ) and \ in the URL.
+  t = t.replace(/\[([^\]\n]*)\]\(([^)\n]+)\)/g, (_m, text: string, url: string) =>
+    put("[" + escapeMdV2(text) + "](" + url.replace(/[)\\]/g, "\\$&") + ")"),
+  );
+  // Bold **x** → *x*
+  t = t.replace(/\*\*([^*\n]+)\*\*/g, (_m, inner: string) => put("*" + escapeMdV2(inner) + "*"));
+  // Italic _x_ (not inside a word) and *x* → _x_
+  t = t.replace(/(?<!\w)_([^_\n]+)_(?!\w)/g, (_m, inner: string) => put("_" + escapeMdV2(inner) + "_"));
+  t = t.replace(/\*([^*\n]+)\*/g, (_m, inner: string) => put("_" + escapeMdV2(inner) + "_"));
+  // Escape everything that remains, then restore the protected fragments.
+  t = escapeMdV2(t);
+  return t.replace(/\uE000(\d+)\uE001/g, (_m, n: string) => stash[Number(n)] ?? "");
+}
+
+/**
+ * Convert assistant-style GitHub markdown to Telegram MarkdownV2. Handles fenced
+ * code blocks, inline code, bold, italic, links, and ATX headings; escapes the
+ * rest. Never throws — any failure falls back to a fully-escaped plain rendering.
+ */
+export function mdToMarkdownV2(md: string): string {
+  try {
+    const lines = md.split("\n");
+    const out: string[] = [];
+    let inFence = false;
+    let fenceLang = "";
+    let buf: string[] = [];
+    const flushFence = (): void => {
+      const lang = fenceLang.replace(/[^a-zA-Z0-9+#_-]/g, "");
+      const body = buf.join("\n").replace(/[`\\]/g, "\\$&");
+      out.push("```" + lang + "\n" + body + "\n```");
+      buf = [];
+      fenceLang = "";
+    };
+
+    for (const line of lines) {
+      const fence = /^\s*```(.*)$/.exec(line);
+      if (fence) {
+        if (inFence) {
+          flushFence();
+          inFence = false;
+        } else {
+          inFence = true;
+          fenceLang = fence[1] ?? "";
+        }
+        continue;
+      }
+      if (inFence) {
+        buf.push(line);
+        continue;
+      }
+      const heading = /^\s*(#{1,6})\s+(.*\S)\s*$/.exec(line);
+      if (heading) {
+        out.push("*" + escapeMdV2(heading[2]) + "*");
+        continue;
+      }
+      out.push(inlineFormat(line));
+    }
+    if (inFence) flushFence(); // unbalanced fence — close it so the send can't break
+    return out.join("\n");
+  } catch {
+    return escapeMdV2(md);
+  }
+}
+
+/** Base splitter: prefer paragraph, then line, then space breaks past limit/2, else hard cut. */
+function splitToLimit(text: string, limit: number, mode: "length" | "newline"): string[] {
+  if (text.length <= limit) return [text];
+  const out: string[] = [];
+  let rest = text;
+  while (rest.length > limit) {
+    let cut = limit;
+    if (mode === "newline") {
+      const para = rest.lastIndexOf("\n\n", limit);
+      const line = rest.lastIndexOf("\n", limit);
+      const space = rest.lastIndexOf(" ", limit);
+      cut = para > limit / 2 ? para : line > limit / 2 ? line : space > 0 ? space : limit;
+    }
+    out.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^\n+/, "");
+  }
+  if (rest) out.push(rest);
+  return out;
+}
+
+/**
+ * Split text into Telegram-sized chunks. Ports the Claude plugin's chunker and
+ * adds fence repair: if a boundary lands inside an open ``` block, the block is
+ * closed at the chunk end and reopened at the next chunk start (language is
+ * dropped on the reopened half). Empty input yields no chunks.
+ */
+export function chunk(text: string, limit: number, mode: "length" | "newline"): string[] {
+  if (text.length === 0) return [];
+  const raw = splitToLimit(text, Math.max(1, limit), mode);
+  const out: string[] = [];
+  let carryOpen = false;
+  for (let piece of raw) {
+    if (carryOpen) piece = "```\n" + piece;
+    const fences = (piece.match(/```/g) ?? []).length;
+    if (fences % 2 === 1) {
+      piece = piece + "\n```";
+      carryOpen = true;
+    } else {
+      carryOpen = false;
+    }
+    out.push(piece);
+  }
+  return out;
+}
+
+/** Width reserved for the `(i/n)` label prepended to every part of a split message. */
+export const PART_LABEL_RESERVE = 16;
+
+/**
+ * Chunk like {@link chunk}, but when the message does not arrive in one piece
+ * prepend `(i/n)` to every part so a reader can see the answer continues. The
+ * text is re-split against a smaller budget so the label always fits.
+ *
+ * `priorParts` counts messages of the same answer already delivered (a stream
+ * preview committed mid-turn), so the numbering spans the whole answer.
+ */
+export function chunkLabeled(text: string, limit: number, mode: "length" | "newline", priorParts = 0): string[] {
+  const parts = chunk(text, limit, mode);
+  if (parts.length <= 1 && priorParts === 0) return parts;
+  const labelled = chunk(text, Math.max(1, limit - PART_LABEL_RESERVE), mode);
+  const total = priorParts + labelled.length;
+  return labelled.map((part, i) => `(${priorParts + i + 1}/${total})\n${part}`);
+}