auggy 0.3.0

package/src/telegram-client.ts

@@ -0,0 +1,145 @@
+/**
+ * Shared Telegram bot API client.
+ *
+ * Used by both `notify`'s telegram adapter and `telegramTransport`. NOT a
+ * cross-augment dependency — peer library import only. Mirrors the shared-
+ * utility pattern of `src/http.ts` and `src/engines/_shared/cost.ts`.
+ *
+ * Future bot-API surface (file uploads, editMessageText for streaming-edit
+ * replies, reactions, inline keyboards) MUST land here, not be duplicated
+ * across notify and telegramTransport.
+ */
+
+import type { HttpClient } from "./http";
+import { createHttpClient } from "./http";
+
+export interface SendMessageOptions {
+  parseMode?: "Markdown" | "HTML" | "MarkdownV2";
+  replyToMessageId?: number;
+  disableNotification?: boolean;
+}
+
+export interface SendMessageResult {
+  messageId: number;
+  chatId: number | string;
+}
+
+export interface GetUpdatesOptions {
+  offset?: number;
+  timeoutSec?: number;
+  allowedUpdates?: string[];
+}
+
+export interface SetWebhookOptions {
+  allowedUpdates?: string[];
+  dropPendingUpdates?: boolean;
+}
+
+export interface TelegramUpdate {
+  update_id: number;
+  message?: TelegramMessage;
+}
+
+export interface TelegramMessage {
+  message_id: number;
+  from?: { id: number; is_bot: boolean; first_name?: string; username?: string };
+  chat: { id: number; type: string };
+  date: number;
+  text?: string;
+}
+
+export interface TelegramChat {
+  id: number;
+  type: string;
+  title?: string;
+  first_name?: string;
+  username?: string;
+}
+
+export interface TelegramBotClient {
+  sendMessage(
+    chatId: number | string,
+    text: string,
+    opts?: SendMessageOptions,
+  ): Promise<SendMessageResult>;
+  getUpdates(opts: GetUpdatesOptions): Promise<TelegramUpdate[]>;
+  setWebhook(url: string, secretToken: string, opts?: SetWebhookOptions): Promise<void>;
+  deleteWebhook(): Promise<void>;
+  getChat(chatId: number | string): Promise<TelegramChat>;
+}
+
+export interface CreateTelegramBotClientOptions {
+  botToken: string;
+  client?: Pick<HttpClient, "post">;
+  baseUrl?: string;
+}
+
+interface BotApiResponse<T> {
+  ok: boolean;
+  result?: T;
+  description?: string;
+  error_code?: number;
+}
+
+export function createTelegramBotClient(opts: CreateTelegramBotClientOptions): TelegramBotClient {
+  const baseUrl = opts.baseUrl ?? "https://api.telegram.org";
+  const url = (method: string) => `${baseUrl}/bot${opts.botToken}/${method}`;
+  const http =
+    opts.client ?? createHttpClient({ timeoutMs: 60_000, userAgent: "auggy-telegram/0.1" });
+
+  async function call<T>(method: string, body: Record<string, unknown>): Promise<T> {
+    const res = await http.post(url(method), {
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    let parsed: BotApiResponse<T>;
+    try {
+      parsed = JSON.parse(res.body) as BotApiResponse<T>;
+    } catch {
+      throw new Error(`Telegram bot API ${method}: non-JSON response (${res.status})`);
+    }
+    if (!parsed.ok) {
+      throw new Error(
+        `Telegram bot API ${method}: ${parsed.description ?? "unknown error"} (${res.status})`,
+      );
+    }
+    return parsed.result as T;
+  }
+
+  return {
+    async sendMessage(chatId, text, sendOpts) {
+      const body: Record<string, unknown> = { chat_id: chatId, text };
+      if (sendOpts?.parseMode) body.parse_mode = sendOpts.parseMode;
+      if (sendOpts?.replyToMessageId != null) body.reply_to_message_id = sendOpts.replyToMessageId;
+      if (sendOpts?.disableNotification) body.disable_notification = true;
+      const result = await call<{ message_id: number; chat: { id: number | string } }>(
+        "sendMessage",
+        body,
+      );
+      return { messageId: result.message_id, chatId: result.chat.id };
+    },
+
+    async getUpdates(getOpts) {
+      const body: Record<string, unknown> = {};
+      if (getOpts.offset != null) body.offset = getOpts.offset;
+      if (getOpts.timeoutSec != null) body.timeout = getOpts.timeoutSec;
+      if (getOpts.allowedUpdates) body.allowed_updates = getOpts.allowedUpdates;
+      return await call<TelegramUpdate[]>("getUpdates", body);
+    },
+
+    async setWebhook(webhookUrl, secretToken, webhookOpts) {
+      const body: Record<string, unknown> = { url: webhookUrl, secret_token: secretToken };
+      if (webhookOpts?.allowedUpdates) body.allowed_updates = webhookOpts.allowedUpdates;
+      if (webhookOpts?.dropPendingUpdates) body.drop_pending_updates = true;
+      await call<true>("setWebhook", body);
+    },
+
+    async deleteWebhook() {
+      await call<true>("deleteWebhook", {});
+    },
+
+    async getChat(chatId) {
+      return await call<TelegramChat>("getChat", { chat_id: chatId });
+    },
+  };
+}

package/src/tokenizer.ts

@@ -0,0 +1,14 @@
+export interface Tokenizer {
+  count(text: string): number;
+}
+
+export function createTokenizer(): Tokenizer {
+  return {
+    count(text: string): number {
+      if (text.length === 0) return 0;
+      // ~4 chars per token approximation. Accurate to ±15% for English.
+      // Replace with tiktoken for production accuracy.
+      return Math.ceil(text.length / 4);
+    },
+  };
+}

package/src/transports/ag-ui-events.ts

@@ -0,0 +1,253 @@
+import type { KernelEvent, TaskState } from "../types";
+
+// === AG-UI event shapes (subset we emit in v1) ===
+// These match the AG-UI spec at https://docs.ag-ui.com/concepts/events.md
+
+export interface AGUIBaseEvent {
+  type: string;
+  timestamp?: number;
+}
+
+export interface AGUIRunStarted extends AGUIBaseEvent {
+  type: "RUN_STARTED";
+  threadId: string;
+  runId: string;
+  parentRunId?: string;
+}
+
+export interface AGUIRunFinished extends AGUIBaseEvent {
+  type: "RUN_FINISHED";
+  threadId: string;
+  runId: string;
+  /**
+   * Optional structured result. v1 carries the terminal status discriminator
+   * so consumers can distinguish "agent finished" from "agent waiting for
+   * user input." Old AG-UI clients that ignore `result` keep working.
+   */
+  result?: {
+    status: TaskState;
+    message?: string;
+  };
+}
+
+export interface AGUIRunError extends AGUIBaseEvent {
+  type: "RUN_ERROR";
+  message: string;
+  code?: string;
+}
+
+export interface AGUITextMessageStart extends AGUIBaseEvent {
+  type: "TEXT_MESSAGE_START";
+  messageId: string;
+  role: "assistant" | "user" | "system" | "tool" | "developer";
+}
+
+export interface AGUITextMessageContent extends AGUIBaseEvent {
+  type: "TEXT_MESSAGE_CONTENT";
+  messageId: string;
+  delta: string;
+}
+
+export interface AGUITextMessageEnd extends AGUIBaseEvent {
+  type: "TEXT_MESSAGE_END";
+  messageId: string;
+}
+
+export interface AGUIToolCallStart extends AGUIBaseEvent {
+  type: "TOOL_CALL_START";
+  toolCallId: string;
+  toolCallName: string;
+  parentMessageId?: string;
+}
+
+export interface AGUIToolCallArgs extends AGUIBaseEvent {
+  type: "TOOL_CALL_ARGS";
+  toolCallId: string;
+  delta: string;
+}
+
+export interface AGUIToolCallEnd extends AGUIBaseEvent {
+  type: "TOOL_CALL_END";
+  toolCallId: string;
+}
+
+export interface AGUIToolCallResult extends AGUIBaseEvent {
+  type: "TOOL_CALL_RESULT";
+  messageId: string;
+  toolCallId: string;
+  content: string;
+  role?: "tool";
+}
+
+export type AGUIEvent =
+  | AGUIRunStarted
+  | AGUIRunFinished
+  | AGUIRunError
+  | AGUITextMessageStart
+  | AGUITextMessageContent
+  | AGUITextMessageEnd
+  | AGUIToolCallStart
+  | AGUIToolCallArgs
+  | AGUIToolCallEnd
+  | AGUIToolCallResult;
+
+// === Constructor helpers ===
+
+export function runStarted(opts: { threadId: string; runId: string }): AGUIRunStarted {
+  return { type: "RUN_STARTED", ...opts };
+}
+
+export function runFinished(opts: {
+  threadId: string;
+  runId: string;
+  status?: TaskState;
+  message?: string;
+}): AGUIRunFinished {
+  const base: AGUIRunFinished = {
+    type: "RUN_FINISHED",
+    threadId: opts.threadId,
+    runId: opts.runId,
+  };
+  if (opts.status !== undefined) {
+    base.result = opts.message
+      ? { status: opts.status, message: opts.message }
+      : { status: opts.status };
+  }
+  return base;
+}
+
+export function runError(opts: { message: string; code?: string }): AGUIRunError {
+  return { type: "RUN_ERROR", ...opts };
+}
+
+export function textMessageStart(opts: {
+  messageId: string;
+  role: AGUITextMessageStart["role"];
+}): AGUITextMessageStart {
+  return { type: "TEXT_MESSAGE_START", ...opts };
+}
+
+export function textMessageContent(opts: {
+  messageId: string;
+  delta: string;
+}): AGUITextMessageContent {
+  return { type: "TEXT_MESSAGE_CONTENT", ...opts };
+}
+
+export function textMessageEnd(opts: { messageId: string }): AGUITextMessageEnd {
+  return { type: "TEXT_MESSAGE_END", ...opts };
+}
+
+export function toolCallStart(opts: {
+  toolCallId: string;
+  toolCallName: string;
+  parentMessageId?: string;
+}): AGUIToolCallStart {
+  return { type: "TOOL_CALL_START", ...opts };
+}
+
+export function toolCallArgs(opts: { toolCallId: string; delta: string }): AGUIToolCallArgs {
+  return { type: "TOOL_CALL_ARGS", ...opts };
+}
+
+export function toolCallEnd(opts: { toolCallId: string }): AGUIToolCallEnd {
+  return { type: "TOOL_CALL_END", ...opts };
+}
+
+export function toolCallResult(opts: {
+  messageId: string;
+  toolCallId: string;
+  content: string;
+}): AGUIToolCallResult {
+  return { type: "TOOL_CALL_RESULT", role: "tool", ...opts };
+}
+
+// === Kernel → AG-UI translation ===
+
+/**
+ * Translate a single kernel event into zero or more AG-UI events.
+ * Some kernel events map 1:1, others expand (e.g. text_message emits
+ * a START / CONTENT / END triple since v1 doesn't stream tokens).
+ *
+ * Note: run_finished and run_error emit events with empty threadId —
+ * the transport patches it before serialization, since threadId is
+ * known at the transport layer.
+ */
+export function translateKernelEvent(event: KernelEvent): AGUIEvent[] {
+  switch (event.kind) {
+    case "run_started":
+      return [runStarted({ threadId: event.threadId, runId: event.turnId })];
+
+    case "tool_call_started":
+      return [
+        toolCallStart({
+          toolCallId: event.toolCallId,
+          toolCallName: event.toolName,
+        }),
+      ];
+
+    case "tool_call_args":
+      return [
+        toolCallArgs({
+          toolCallId: event.toolCallId,
+          delta: JSON.stringify(event.args),
+        }),
+      ];
+
+    case "tool_call_result":
+      return [
+        toolCallEnd({ toolCallId: event.toolCallId }),
+        toolCallResult({
+          messageId: `${event.toolCallId}-result`,
+          toolCallId: event.toolCallId,
+          content: event.output,
+        }),
+      ];
+
+    case "text_message":
+      return [
+        textMessageStart({ messageId: event.messageId, role: event.role }),
+        textMessageContent({ messageId: event.messageId, delta: event.text }),
+        textMessageEnd({ messageId: event.messageId }),
+      ];
+
+    // Streaming text lifecycle: emitted by engines that support onDelta.
+    // Each maps 1:1 to its AG-UI counterpart.
+    case "text_message_start":
+      return [textMessageStart({ messageId: event.messageId, role: event.role })];
+
+    case "text_message_delta":
+      return [textMessageContent({ messageId: event.messageId, delta: event.delta })];
+
+    case "text_message_end":
+      return [textMessageEnd({ messageId: event.messageId })];
+
+    case "run_finished":
+      return [
+        runFinished({
+          threadId: "",
+          runId: event.turnId,
+          status: event.status,
+          ...(event.message !== undefined && { message: event.message }),
+        }),
+      ];
+
+    case "run_error":
+      // Only emit RUN_ERROR here. The turn loop always emits a separate
+      // run_finished kernel event after run_error (see turn-loop.ts), which
+      // produces the terminal RUN_FINISHED. Emitting one here would cause
+      // clients to see two terminal events for a single failing turn.
+      return [runError({ message: event.message, code: event.source })];
+  }
+}
+
+// === SSE serialization ===
+
+/**
+ * Format an AG-UI event as a single Server-Sent Events data frame.
+ * Each event is a JSON object prefixed with `data: ` and followed
+ * by two newlines to mark the end of the frame.
+ */
+export function serializeSSE(event: AGUIEvent): string {
+  return `data: ${JSON.stringify(event)}\n\n`;
+}

package/src/transports/visitor-token.ts

@@ -0,0 +1,82 @@
+export interface VisitorTokenPayload {
+  visitorId: string;
+  agentId: string;
+  issuedAt: number;
+  expiresAt: number;
+}
+
+const PURPOSE = "auggy-visitor-signing";
+const encoder = new TextEncoder();
+
+export async function deriveSigningKey(bearerToken: string): Promise<CryptoKey> {
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(bearerToken),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const derived = await crypto.subtle.sign("HMAC", keyMaterial, encoder.encode(PURPOSE));
+  return crypto.subtle.importKey("raw", derived, { name: "HMAC", hash: "SHA-256" }, true, [
+    "sign",
+    "verify",
+  ]);
+}
+
+export async function createVisitorToken(
+  key: CryptoKey,
+  agentId: string,
+  ttlSeconds: number,
+  /**
+   * Optional pre-existing visitorId. When omitted (the common case for first
+   * verification or anonymous-recognized issuance), a fresh `vis_<uuid>` is
+   * minted. When provided (re-verification of an already-known email), the
+   * existing identifier is preserved so peer-scoped state in layered-memory
+   * remains continuous across re-verifications.
+   */
+  existingVisitorId?: string,
+): Promise<{ token: string; payload: VisitorTokenPayload }> {
+  const payload: VisitorTokenPayload = {
+    visitorId: existingVisitorId ?? `vis_${crypto.randomUUID()}`,
+    agentId,
+    issuedAt: Date.now(),
+    expiresAt: Date.now() + ttlSeconds * 1000,
+  };
+  const payloadB64 = btoa(JSON.stringify(payload));
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payloadB64));
+  const sigB64 = btoa(String.fromCharCode(...new Uint8Array(signature)));
+  return { token: `${payloadB64}.${sigB64}`, payload };
+}
+
+export async function verifyVisitorToken(
+  key: CryptoKey,
+  token: string,
+): Promise<VisitorTokenPayload | null> {
+  const parts = token.split(".");
+  if (parts.length !== 2) return null;
+  const [payloadB64, sigB64] = parts as [string, string];
+
+  let sigBytes: Uint8Array;
+  try {
+    sigBytes = Uint8Array.from(atob(sigB64), (c) => c.charCodeAt(0));
+  } catch {
+    return null;
+  }
+
+  const sigBuffer = sigBytes.buffer.slice(
+    sigBytes.byteOffset,
+    sigBytes.byteOffset + sigBytes.byteLength,
+  ) as ArrayBuffer;
+  const valid = await crypto.subtle.verify("HMAC", key, sigBuffer, encoder.encode(payloadB64));
+  if (!valid) return null;
+
+  let payload: VisitorTokenPayload;
+  try {
+    payload = JSON.parse(atob(payloadB64)) as VisitorTokenPayload;
+  } catch {
+    return null;
+  }
+
+  if (payload.expiresAt < Date.now()) return null;
+  return payload;
+}