clawless 0.1.2

package/messaging/telegramClient.ts

@@ -0,0 +1,132 @@
+import { Telegraf } from 'telegraf';
+
+function splitTextIntoChunks(text: string, maxMessageLength: number): string[] {
+  const normalizedText = String(text || '');
+  if (!normalizedText) {
+    return [''];
+  }
+
+  if (normalizedText.length <= maxMessageLength) {
+    return [normalizedText];
+  }
+
+  const chunks: string[] = [];
+  let start = 0;
+
+  while (start < normalizedText.length) {
+    const end = Math.min(start + maxMessageLength, normalizedText.length);
+    chunks.push(normalizedText.slice(start, end));
+    start = end;
+  }
+
+  return chunks;
+}
+
+class TelegramMessageContext {
+  ctx: any;
+  typingIntervalMs: number;
+  maxMessageLength: number;
+  text: string;
+  chatId: string | number | undefined;
+
+  constructor(ctx: any, typingIntervalMs: number, maxMessageLength: number) {
+    this.ctx = ctx;
+    this.typingIntervalMs = typingIntervalMs;
+    this.maxMessageLength = maxMessageLength;
+    this.text = ctx.message?.text || '';
+    this.chatId = ctx.chat?.id;
+  }
+
+  startTyping() {
+    this.ctx.telegram.sendChatAction(this.ctx.chat.id, 'typing').catch(() => {});
+
+    const intervalId = setInterval(() => {
+      this.ctx.telegram.sendChatAction(this.ctx.chat.id, 'typing').catch(() => {});
+    }, this.typingIntervalMs);
+
+    return () => clearInterval(intervalId);
+  }
+
+  async sendText(text: string) {
+    const chunks = splitTextIntoChunks(text, this.maxMessageLength);
+    for (const chunk of chunks) {
+      await this.ctx.reply(chunk);
+    }
+  }
+
+  async startLiveMessage(initialText = '…') {
+    const sent = await this.ctx.reply(initialText);
+    return sent?.message_id as number | undefined;
+  }
+
+  async updateLiveMessage(messageId: number, text: string) {
+    await this.ctx.telegram.editMessageText(this.ctx.chat.id, messageId, undefined, text || '…');
+  }
+
+  async finalizeLiveMessage(messageId: number, text: string) {
+    const finalText = text || 'No response received.';
+    const chunks = splitTextIntoChunks(finalText, this.maxMessageLength);
+
+    try {
+      await this.updateLiveMessage(messageId, chunks[0] || 'No response received.');
+    } catch (error: any) {
+      const errorMessage = String(error?.message || '').toLowerCase();
+      if (!errorMessage.includes('message is not modified')) {
+        throw error;
+      }
+    }
+
+    for (let index = 1; index < chunks.length; index += 1) {
+      await this.ctx.reply(chunks[index]);
+    }
+  }
+
+  async removeMessage(messageId: number) {
+    await this.ctx.telegram.deleteMessage(this.ctx.chat.id, messageId);
+  }
+}
+
+export class TelegramMessagingClient {
+  bot: Telegraf;
+  typingIntervalMs: number;
+  maxMessageLength: number;
+
+  constructor({ token, typingIntervalMs, maxMessageLength }: { token: string; typingIntervalMs: number; maxMessageLength: number }) {
+    this.bot = new Telegraf(token);
+    this.typingIntervalMs = typingIntervalMs;
+    this.maxMessageLength = maxMessageLength;
+  }
+
+  onTextMessage(handler: (messageContext: TelegramMessageContext) => Promise<void> | void) {
+    this.bot.on('text', (ctx) => {
+      const messageContext = new TelegramMessageContext(ctx, this.typingIntervalMs, this.maxMessageLength);
+      Promise.resolve(handler(messageContext)).catch((error) => {
+        console.error('Text message handler failed:', error);
+      });
+    });
+  }
+
+  onError(handler: (error: Error, messageContext: TelegramMessageContext | null) => void) {
+    this.bot.catch((error, ctx) => {
+      const messageContext = ctx?.chat
+        ? new TelegramMessageContext(ctx, this.typingIntervalMs, this.maxMessageLength)
+        : null;
+      handler(error as Error, messageContext);
+    });
+  }
+
+  async launch() {
+    await this.bot.launch();
+  }
+
+  async sendTextToChat(chatId: string | number, text: string) {
+    const chunks = splitTextIntoChunks(text, this.maxMessageLength);
+    for (const chunk of chunks) {
+      await this.bot.telegram.sendMessage(chatId, chunk);
+    }
+  }
+
+  stop(reason: string) {
+    this.bot.stop(reason);
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "clawless",
+  "version": "0.1.2",
+  "description": "A bridge connecting Telegram to Agent Gemini CLI using Agent Communication Protocol (ACP)",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "clawless": "./dist/bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx watch ./bin/cli.ts",
+    "start": "tsx ./bin/cli.ts",
+    "cli": "tsx ./bin/cli.ts",
+    "callback:health": "./scripts/callback-health.sh",
+    "callback:test": "./scripts/callback-post.sh",
+    "callback:test:chat": "./scripts/callback-post-chat.sh"
+  },
+  "keywords": [
+    "telegram",
+    "gemini",
+    "acp",
+    "agent",
+    "ai"
+  ],
+  "author": "Hainan Zhao",
+  "license": "MIT",
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.14.1",
+    "dotenv": "^16.4.5",
+    "node-cron": "^4.2.1",
+    "telegraf": "^4.16.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "@types/node-cron": "^3.0.11",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scheduler/cronScheduler.ts

@@ -0,0 +1,355 @@
+import cron from 'node-cron';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getErrorMessage } from '../utils/error.js';
+
+export interface ScheduleConfig {
+  id: string;
+  cronExpression?: string;
+  oneTime?: boolean;
+  runAt?: Date;
+  message: string;
+  description?: string;
+  createdAt: Date;
+  lastRun?: Date;
+  active: boolean;
+}
+
+export interface ScheduleJob {
+  config: ScheduleConfig;
+  task?: cron.ScheduledTask;
+  timeout?: NodeJS.Timeout;
+  inFlight?: boolean;
+}
+
+interface PersistedScheduleConfig {
+  id: string;
+  cronExpression?: string;
+  oneTime?: boolean;
+  runAt?: string;
+  message: string;
+  description?: string;
+  createdAt: string;
+  lastRun?: string;
+  active: boolean;
+}
+
+export interface CronSchedulerOptions {
+  persistenceFilePath?: string;
+  timezone?: string;
+  logInfo?: (message: string, details?: unknown) => void;
+}
+
+export class CronScheduler {
+  private jobs: Map<string, ScheduleJob> = new Map();
+  private jobCallback: (schedule: ScheduleConfig) => Promise<void>;
+  private persistenceFilePath: string | null;
+  private timezone: string;
+  private logInfo: (message: string, details?: unknown) => void;
+
+  constructor(callback: (schedule: ScheduleConfig) => Promise<void>, options: CronSchedulerOptions = {}) {
+    this.jobCallback = callback;
+    this.persistenceFilePath = options.persistenceFilePath || null;
+    this.timezone = options.timezone || process.env.TZ || 'UTC';
+    this.logInfo = options.logInfo || ((message: string, details?: unknown) => {
+      if (details !== undefined) {
+        console.log(`[CronScheduler] ${message}`, details);
+      } else {
+        console.log(`[CronScheduler] ${message}`);
+      }
+    });
+
+    this.loadPersistedSchedules();
+  }
+
+  private validateScheduleConfig(config: ScheduleConfig): void {
+    if (config.oneTime) {
+      if (!config.runAt) {
+        throw new Error('One-time schedules require a runAt date');
+      }
+      if (config.runAt <= new Date()) {
+        throw new Error('One-time schedule runAt must be in the future');
+      }
+      return;
+    }
+
+    if (!config.cronExpression) {
+      throw new Error('Recurring schedules require a cronExpression');
+    }
+
+    if (!cron.validate(config.cronExpression)) {
+      throw new Error('Invalid cron expression');
+    }
+  }
+
+  private configureRuntimeForJob(job: ScheduleJob): void {
+    // Clean existing runtime handles first (used when toggling/reloading)
+    if (job.task) {
+      job.task.stop();
+      job.task = undefined;
+    }
+    if (job.timeout) {
+      clearTimeout(job.timeout);
+      job.timeout = undefined;
+    }
+
+    const { config } = job;
+
+    if (config.oneTime && config.runAt) {
+      if (!config.active) {
+        return;
+      }
+
+      const delay = config.runAt.getTime() - Date.now();
+      if (delay <= 0) {
+        return;
+      }
+
+      job.timeout = setTimeout(async () => {
+        await this.executeJob(config.id);
+        this.removeSchedule(config.id);
+      }, delay);
+      return;
+    }
+
+    if (config.cronExpression) {
+      job.task = cron.schedule(
+        config.cronExpression,
+        async () => {
+          await this.executeJob(config.id);
+        },
+        {
+          timezone: this.timezone,
+        }
+      );
+
+      if (!config.active) {
+        job.task.stop();
+      }
+    }
+  }
+
+  private toPersistedSchedule(config: ScheduleConfig): PersistedScheduleConfig {
+    return {
+      id: config.id,
+      cronExpression: config.cronExpression,
+      oneTime: config.oneTime,
+      runAt: config.runAt ? config.runAt.toISOString() : undefined,
+      message: config.message,
+      description: config.description,
+      createdAt: config.createdAt.toISOString(),
+      lastRun: config.lastRun ? config.lastRun.toISOString() : undefined,
+      active: config.active,
+    };
+  }
+
+  private parsePersistedSchedule(config: PersistedScheduleConfig): ScheduleConfig {
+    return {
+      id: config.id,
+      cronExpression: config.cronExpression,
+      oneTime: config.oneTime,
+      runAt: config.runAt ? new Date(config.runAt) : undefined,
+      message: config.message,
+      description: config.description,
+      createdAt: new Date(config.createdAt),
+      lastRun: config.lastRun ? new Date(config.lastRun) : undefined,
+      active: config.active,
+    };
+  }
+
+  private persistSchedules(): void {
+    if (!this.persistenceFilePath) {
+      return;
+    }
+
+    try {
+      fs.mkdirSync(path.dirname(this.persistenceFilePath), { recursive: true });
+      const schedules = Array.from(this.jobs.values()).map((job) => this.toPersistedSchedule(job.config));
+      fs.writeFileSync(this.persistenceFilePath, `${JSON.stringify({ schedules }, null, 2)}\n`, 'utf8');
+    } catch (error) {
+      this.logInfo('Failed to persist schedules', {
+        persistenceFilePath: this.persistenceFilePath,
+        error: getErrorMessage(error),
+      });
+    }
+  }
+
+  private loadPersistedSchedules(): void {
+    if (!this.persistenceFilePath) {
+      return;
+    }
+
+    try {
+      if (!fs.existsSync(this.persistenceFilePath)) {
+        return;
+      }
+
+      const raw = fs.readFileSync(this.persistenceFilePath, 'utf8');
+      const parsed = JSON.parse(raw) as { schedules?: PersistedScheduleConfig[] };
+      const schedules = Array.isArray(parsed?.schedules) ? parsed.schedules : [];
+      const now = new Date();
+
+      for (const persisted of schedules) {
+        const config = this.parsePersistedSchedule(persisted);
+
+        // Drop one-time schedules that are already past due on restart
+        if (config.oneTime && config.runAt && config.runAt <= now) {
+          continue;
+        }
+
+        if (!config.oneTime && (!config.cronExpression || !cron.validate(config.cronExpression))) {
+          this.logInfo('Skipping invalid persisted recurring schedule', { scheduleId: config.id });
+          continue;
+        }
+
+        const job: ScheduleJob = { config };
+        this.configureRuntimeForJob(job);
+        this.jobs.set(config.id, job);
+      }
+
+      this.logInfo('Loaded persisted schedules', {
+        count: this.jobs.size,
+        persistenceFilePath: this.persistenceFilePath,
+      });
+
+      // Clean up persisted file if we dropped stale entries
+      this.persistSchedules();
+    } catch (error) {
+      this.logInfo('Failed to load persisted schedules', {
+        persistenceFilePath: this.persistenceFilePath,
+        error: getErrorMessage(error),
+      });
+    }
+  }
+
+  /**
+   * Create a new schedule
+   */
+  createSchedule(config: Omit<ScheduleConfig, 'id' | 'createdAt' | 'active'>): ScheduleConfig {
+    const scheduleConfig: ScheduleConfig = {
+      ...config,
+      id: this.generateId(),
+      createdAt: new Date(),
+      active: true,
+    };
+
+    this.validateScheduleConfig(scheduleConfig);
+
+    const job: ScheduleJob = {
+      config: scheduleConfig,
+    };
+
+    this.configureRuntimeForJob(job);
+
+    this.jobs.set(scheduleConfig.id, job);
+    this.persistSchedules();
+    return scheduleConfig;
+  }
+
+  /**
+   * Execute a scheduled job
+   */
+  private async executeJob(scheduleId: string): Promise<void> {
+    const job = this.jobs.get(scheduleId);
+    if (!job || !job.config.active) {
+      return;
+    }
+
+    // Skip if job is already in flight (prevents overlapping executions)
+    if (job.inFlight) {
+      console.warn(`[CronScheduler] Job ${scheduleId} skipped - previous execution still in progress`);
+      return;
+    }
+
+    job.inFlight = true;
+    job.config.lastRun = new Date();
+    this.persistSchedules();
+
+    try {
+      await this.jobCallback(job.config);
+    } catch (error: any) {
+      console.error(`[CronScheduler] Job ${scheduleId} execution failed: ${getErrorMessage(error)}`);
+    } finally {
+      job.inFlight = false;
+    }
+  }
+
+  /**
+   * Get a schedule by ID
+   */
+  getSchedule(scheduleId: string): ScheduleConfig | null {
+    const job = this.jobs.get(scheduleId);
+    return job ? job.config : null;
+  }
+
+  /**
+   * List all schedules
+   */
+  listSchedules(): ScheduleConfig[] {
+    return Array.from(this.jobs.values()).map(job => job.config);
+  }
+
+  /**
+   * Remove a schedule
+   */
+  removeSchedule(scheduleId: string): boolean {
+    const job = this.jobs.get(scheduleId);
+    if (!job) {
+      return false;
+    }
+
+    // Stop the cron task if it exists
+    if (job.task) {
+      job.task.stop();
+    }
+
+    // Clear timeout if it exists (for one-time jobs)
+    if (job.timeout) {
+      clearTimeout(job.timeout);
+    }
+
+    this.jobs.delete(scheduleId);
+    this.persistSchedules();
+    return true;
+  }
+
+  /**
+   * Pause/resume a schedule
+   */
+  toggleSchedule(scheduleId: string, active: boolean): boolean {
+    const job = this.jobs.get(scheduleId);
+    if (!job) {
+      return false;
+    }
+
+    job.config.active = active;
+
+    if (job.task) {
+      if (active) {
+        job.task.start();
+      } else {
+        job.task.stop();
+      }
+    }
+
+    this.persistSchedules();
+
+    return true;
+  }
+
+  /**
+   * Generate a unique ID for a schedule
+   */
+  private generateId(): string {
+    return `schedule_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  /**
+   * Shutdown all scheduled jobs
+   */
+  shutdown(): void {
+    for (const [scheduleId] of this.jobs) {
+      this.removeSchedule(scheduleId);
+    }
+  }
+}

package/scheduler/scheduledJobHandler.ts

@@ -0,0 +1,55 @@
+import { ScheduleConfig } from './cronScheduler.js';
+import { getErrorMessage } from '../utils/error.js';
+
+export interface ScheduledJobHandlerDeps {
+  logInfo: (message: string, details?: unknown) => void;
+  buildPromptWithMemory: (userPrompt: string) => string;
+  runScheduledPromptWithTempAcp: (promptForGemini: string, scheduleId: string) => Promise<string>;
+  resolveTargetChatId: () => string | null;
+  sendTextToChat: (chatId: string | number, text: string) => Promise<void>;
+  normalizeOutgoingText: (text: unknown) => string;
+}
+
+export function createScheduledJobHandler(deps: ScheduledJobHandlerDeps) {
+  const {
+    logInfo,
+    buildPromptWithMemory,
+    runScheduledPromptWithTempAcp,
+    resolveTargetChatId,
+    sendTextToChat,
+    normalizeOutgoingText,
+  } = deps;
+
+  return async function handleScheduledJob(schedule: ScheduleConfig): Promise<void> {
+    logInfo('Executing scheduled job', { scheduleId: schedule.id, message: schedule.message });
+
+    try {
+      const promptForGemini = buildPromptWithMemory(schedule.message);
+      logInfo('Scheduler prompt payload sent to Gemini', {
+        scheduleId: schedule.id,
+        prompt: promptForGemini,
+      });
+
+      const response = await runScheduledPromptWithTempAcp(promptForGemini, schedule.id);
+
+      const targetChatId = resolveTargetChatId();
+      if (targetChatId) {
+        await sendTextToChat(targetChatId, normalizeOutgoingText(response));
+        logInfo('Scheduled job result sent to Telegram', { scheduleId: schedule.id, chatId: targetChatId });
+      } else {
+        logInfo('No target chat available for scheduled job result', { scheduleId: schedule.id });
+      }
+    } catch (error: any) {
+      logInfo('Scheduled job execution failed', {
+        scheduleId: schedule.id,
+        error: getErrorMessage(error),
+      });
+
+      const targetChatId = resolveTargetChatId();
+      if (targetChatId) {
+        const errorMessage = `❌ Scheduled task failed: ${schedule.description || schedule.message}\n\nError: ${getErrorMessage(error)}`;
+        await sendTextToChat(targetChatId, normalizeOutgoingText(errorMessage));
+      }
+    }
+  };
+}

package/scripts/callback-health.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="${CALLBACK_BASE_URL:-http://127.0.0.1:8788}"
+curl -sS "$BASE_URL/healthz"
+echo

package/scripts/callback-post-chat.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: $0 <chatId> [message]" >&2
+  exit 1
+fi
+
+CHAT_ID="$1"
+MESSAGE="${2:-Callback test to explicit chat from clawless}"
+BASE_URL="${CALLBACK_BASE_URL:-http://127.0.0.1:8788}"
+ENDPOINT="$BASE_URL/callback/telegram"
+
+if [[ -n "${CALLBACK_AUTH_TOKEN:-}" ]]; then
+  curl -sS -X POST "$ENDPOINT" \
+    -H "Content-Type: application/json" \
+    -H "x-callback-token: ${CALLBACK_AUTH_TOKEN}" \
+    -d "{\"chatId\":\"${CHAT_ID//\"/\\\"}\",\"text\":\"${MESSAGE//\"/\\\"}\"}"
+else
+  curl -sS -X POST "$ENDPOINT" \
+    -H "Content-Type: application/json" \
+    -d "{\"chatId\":\"${CHAT_ID//\"/\\\"}\",\"text\":\"${MESSAGE//\"/\\\"}\"}"
+fi
+
+echo

package/scripts/callback-post.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="${CALLBACK_BASE_URL:-http://127.0.0.1:8788}"
+ENDPOINT="$BASE_URL/callback/telegram"
+MESSAGE="${1:-Callback test from clawless}"
+
+if [[ -n "${CALLBACK_AUTH_TOKEN:-}" ]]; then
+  curl -sS -X POST "$ENDPOINT" \
+    -H "Content-Type: application/json" \
+    -H "x-callback-token: ${CALLBACK_AUTH_TOKEN}" \
+    -d "{\"text\":\"${MESSAGE//\"/\\\"}\"}"
+else
+  curl -sS -X POST "$ENDPOINT" \
+    -H "Content-Type: application/json" \
+    -d "{\"text\":\"${MESSAGE//\"/\\\"}\"}"
+fi
+
+echo