clawlet 0.1.0

package/src/cli.ts

@@ -0,0 +1,189 @@
+import * as readline from 'readline';
+import 'dotenv/config';
+import { Agent, type InputAdapter, type OutputAdapter } from './agent.js';
+import { Bot } from 'grammy';
+
+// --- CLI Input Adapter ---
+
+class CliInput implements InputAdapter {
+  private handler!: (text: string, label: string) => void;
+  private rl: readline.Interface;
+
+  constructor(rl: readline.Interface) {
+    this.rl = rl;
+  }
+
+  onMessage(handler: (text: string, label: string) => void) {
+    this.handler = handler;
+  }
+
+  start() {
+    this.rl.on('line', (input) => {
+      const trimmed = input.trim();
+      if (trimmed === 'exit') process.exit(0);
+      if (!trimmed) { this.rl.prompt(); return; }
+      this.handler(trimmed, 'cli');
+    });
+    this.rl.prompt();
+  }
+}
+
+// --- CLI Output Adapter ---
+
+class CliOutput implements OutputAdapter {
+  constructor(private rl: readline.Interface) {}
+
+  onAgentStart(label: string) {
+    if (label !== 'cli') {
+      readline.clearLine(process.stdout, 0);
+      readline.cursorTo(process.stdout, 0);
+      // The label from telegram input includes the message text via logging in TelegramInput
+    }
+    process.stdout.write("Agent: ");
+  }
+
+  onResponseChunk(chunk: string) {
+    process.stdout.write(chunk);
+  }
+
+  onResponseEnd(_fullResponse: string) {
+    console.log();
+    this.rl.prompt();
+  }
+
+  onError(error: Error) {
+    console.error("\n❌ Error:", error.message);
+    this.rl.prompt();
+  }
+}
+
+// --- Telegram Input Adapter ---
+
+class TelegramInput implements InputAdapter {
+  private handler!: (text: string, label: string) => void;
+  private bot: Bot;
+  private authorizedChatId: string | undefined;
+  /** Shared set so the output adapter knows which chats to send to */
+  private activeChatIds: Set<number>;
+
+  constructor(bot: Bot, activeChatIds: Set<number>, authorizedChatId?: string) {
+    this.bot = bot;
+    this.activeChatIds = activeChatIds;
+    this.authorizedChatId = authorizedChatId;
+  }
+
+  onMessage(handler: (text: string, label: string) => void) {
+    this.handler = handler;
+  }
+
+  start() {
+    this.bot.command("start", (ctx) => ctx.reply("Clawlet is online."));
+
+    this.bot.on("message:text", async (ctx) => {
+      const chatId = ctx.chat.id;
+
+      if (this.authorizedChatId && chatId.toString() !== this.authorizedChatId) {
+        console.log(`Unauthorized access attempt from Telegram chat ID: ${chatId}`);
+        return;
+      }
+
+      this.activeChatIds.add(chatId);
+      console.log(`\n[Telegram] ${ctx.message.text}`);
+      this.handler(ctx.message.text, 'telegram');
+    });
+
+    this.bot.start();
+    console.log("🤖 Telegram Bot started.");
+  }
+}
+
+// --- Telegram Output Adapter ---
+
+class TelegramOutput implements OutputAdapter {
+  private bot: Bot;
+  /** Shared reference to active chat IDs (populated by TelegramInput) */
+  private activeChatIds: Set<number>;
+  private typingInterval: NodeJS.Timeout | null = null;
+
+  constructor(bot: Bot, activeChatIds: Set<number>) {
+    this.bot = bot;
+    this.activeChatIds = activeChatIds;
+  }
+
+  onAgentStart(_label: string) {
+    if (this.activeChatIds.size === 0) return;
+    for (const chatId of this.activeChatIds) {
+      this.bot.api.sendChatAction(chatId, "typing").catch(() => {});
+    }
+    this.typingInterval = setInterval(() => {
+      for (const chatId of this.activeChatIds) {
+        this.bot.api.sendChatAction(chatId, "typing").catch(() => {});
+      }
+    }, 4000);
+  }
+
+  onResponseChunk(_chunk: string) {
+    // Telegram doesn't stream — full message sent at end
+  }
+
+  async onResponseEnd(fullResponse: string) {
+    this.stopTyping();
+    const text = fullResponse.trim() || "✅ Done.";
+    for (const chatId of this.activeChatIds) {
+      try {
+        if (text.length > 4000) {
+          const chunks = text.match(/.{1,4000}/g) || [];
+          for (const chunk of chunks) {
+            await this.bot.api.sendMessage(chatId, chunk);
+          }
+        } else {
+          await this.bot.api.sendMessage(chatId, text);
+        }
+      } catch (e: any) {
+        console.error(`  ⚠️ Failed to send to Telegram chat ${chatId}: ${e.message}`);
+      }
+    }
+  }
+
+  onError(error: Error) {
+    this.stopTyping();
+    for (const chatId of this.activeChatIds) {
+      this.bot.api.sendMessage(chatId, `⚠️ Error: ${error.message}`).catch(() => {});
+    }
+  }
+
+  private stopTyping() {
+    if (this.typingInterval) {
+      clearInterval(this.typingInterval);
+      this.typingInterval = null;
+    }
+  }
+}
+
+// --- MAIN ---
+
+const TELEGRAM_BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
+const TELEGRAM_USERINFO_ID = process.env.TELEGRAM_USERINFO_ID;
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: '\nYou: ' });
+const agent = new Agent();
+
+// Always add CLI adapters
+agent.addInput(new CliInput(rl));
+agent.addOutput(new CliOutput(rl));
+
+// Add Telegram if configured via .env
+if (TELEGRAM_BOT_TOKEN) {
+  const bot = new Bot(TELEGRAM_BOT_TOKEN);
+  const activeChatIds = new Set<number>();
+
+  agent.addInput(new TelegramInput(bot, activeChatIds, TELEGRAM_USERINFO_ID ?? undefined));
+  agent.addOutput(new TelegramOutput(bot, activeChatIds));
+
+  console.log("🤖 Telegram integration enabled.");
+} else {
+  console.log("⚠️ TELEGRAM_BOT_TOKEN not found. Running CLI only.");
+}
+
+console.log("🤖 Clawlet CLI initialized.");
+await agent.start();

package/src/memory.ts

@@ -0,0 +1,47 @@
+import { createStorage, type Storage } from "unstorage";
+import fsDriver from "unstorage/drivers/fs";
+import { type ModelMessage } from "ai";
+import path from "path";
+import { LibSqlKeyValueStorage, LibSqlListStorage, SkillHistoryStorage } from "./storage.js";
+
+export class AgentMemory {
+  // 1. Secrets (libSQL - file:secrets.db)
+  public secrets: LibSqlKeyValueStorage;
+
+  // 2. History (libSQL - file:history.db)
+  public history: LibSqlListStorage<ModelMessage>;
+
+  // 3. Skill History (libSQL - file:history.db, table: skill_history)
+  public skillHistory: SkillHistoryStorage<ModelMessage>;
+
+  // 4. Workspace (Unstorage - ./workspace)
+  public workspace: Storage;
+
+  constructor() {
+    // A. Init Secrets DB
+    // In Production: process.env.SECRETS_DB_URL (libsql://...)
+    this.secrets = new LibSqlKeyValueStorage(
+      process.env.SECRETS_DB_URL || "file:secrets.db", 
+      process.env.SECRETS_AUTH_TOKEN
+    );
+
+    // B. Init History DB
+    // In Production: process.env.HISTORY_DB_URL (libsql://...)
+    this.history = new LibSqlListStorage<ModelMessage>(
+      process.env.HISTORY_DB_URL || "file:history.db",
+      process.env.HISTORY_AUTH_TOKEN
+    );
+
+    // C. Init Skill History (same DB as history, different table)
+    this.skillHistory = new SkillHistoryStorage<ModelMessage>(
+      process.env.HISTORY_DB_URL || "file:history.db",
+      process.env.HISTORY_AUTH_TOKEN
+    );
+
+    // D. Init Workspace (Filesystem)
+    // Unstorage abstrahiert hier nur das "Wie", aber es bleibt lokal im Ordner.
+    this.workspace = createStorage({
+      driver: fsDriver({ base: path.join(process.cwd(), "workspace") })
+    });
+  }
+}

package/src/storage.ts

@@ -0,0 +1,190 @@
+import { createClient, type Client } from '@libsql/client';
+
+// --- A. Key-Value Storage (für Secrets/Config) ---
+export class LibSqlKeyValueStorage {
+  private client: Client;
+  private tableName: string;
+
+  constructor(url: string, authToken?: string, tableName = 'kv_store') {
+    this.tableName = tableName;
+    this.client = createClient({ url, authToken });
+    this.init();
+  }
+
+  private async init() {
+    await this.client.execute(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        key TEXT PRIMARY KEY,
+        value TEXT
+      )
+    `);
+  }
+
+  async set(key: string, value: string) {
+    // Upsert (Insert or Replace)
+    await this.client.execute({
+      sql: `INSERT INTO ${this.tableName} (key, value) VALUES (?, ?)
+            ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+      args: [key, value]
+    });
+  }
+
+  async get(key: string): Promise<string | null> {
+    const rs = await this.client.execute({
+      sql: `SELECT value FROM ${this.tableName} WHERE key = ?`,
+      args: [key]
+    });
+    return (rs.rows[0]?.value as string) || null;
+  }
+
+  async has(key: string): Promise<boolean> {
+    const rs = await this.client.execute({
+      sql: `SELECT 1 FROM ${this.tableName} WHERE key = ? LIMIT 1`,
+      args: [key]
+    });
+    return rs.rows.length > 0;
+  }
+
+  async delete(key: string) {
+    await this.client.execute({
+      sql: `DELETE FROM ${this.tableName} WHERE key = ?`,
+      args: [key]
+    });
+  }
+
+  async listKeys(): Promise<string[]> {
+    const rs = await this.client.execute(`SELECT key FROM ${this.tableName}`);
+    return rs.rows.map(row => row.key as string);
+  }
+}
+
+// --- B. List Storage (für History/Logs) ---
+export class LibSqlListStorage<T = any> {
+  private client: Client;
+  private tableName: string;
+
+  constructor(url: string, authToken?: string, tableName = 'list_store') {
+    this.tableName = tableName;
+    this.client = createClient({ url, authToken });
+    this.init();
+  }
+
+  private async init() {
+    await this.client.execute(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        item TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+  }
+
+  async push(item: T) {
+    await this.client.execute({
+      sql: `INSERT INTO ${this.tableName} (item) VALUES (?)`,
+      args: [JSON.stringify(item)]
+    });
+  }
+
+  // Bulk Insert für Performance
+  async pushMany(items: T[]) {
+    const promises = items.map(item => this.client.execute({
+        sql: `INSERT INTO ${this.tableName} (item) VALUES (?)`,
+        args: [JSON.stringify(item)]
+    }));
+    await Promise.all(promises);
+  }
+
+  async getAll(): Promise<T[]> {
+    const rs = await this.client.execute(
+      `SELECT item FROM ${this.tableName} ORDER BY id ASC`
+    );
+    return rs.rows.map(row => JSON.parse(row.item as string));
+  }
+  
+  // Optional: Nur die letzten N Nachrichten holen (Kontext-Fenster!)
+  async getRecent(limit: number): Promise<T[]> {
+     // Trick: Erst sortieren DESC (neueste), limitieren, dann wieder ASC sortieren
+     const rs = await this.client.execute({
+        sql: `SELECT * FROM (
+                SELECT item, id FROM ${this.tableName} ORDER BY id DESC LIMIT ?
+              ) ORDER BY id ASC`,
+        args: [limit]
+     });
+     return rs.rows.map(row => JSON.parse(row.item as string));
+  }
+
+  async count(): Promise<number> {
+    const rs = await this.client.execute(
+      `SELECT COUNT(*) as cnt FROM ${this.tableName}`
+    );
+    return Number(rs.rows[0]?.cnt ?? 0);
+  }
+
+  async clear() {
+    await this.client.execute(`DELETE FROM ${this.tableName}`);
+    // Reset autoincrement so IDs stay clean
+    await this.client.execute(
+      `DELETE FROM sqlite_sequence WHERE name = '${this.tableName}'`
+    );
+  }
+}
+
+// --- C. Skill History Storage (single table, partitioned by skill name) ---
+export class SkillHistoryStorage<T = any> {
+  private client: Client;
+
+  constructor(url: string, authToken?: string) {
+    this.client = createClient({ url, authToken });
+    this.init();
+  }
+
+  private async init() {
+    await this.client.execute(`
+      CREATE TABLE IF NOT EXISTS skill_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        item TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+  }
+
+  async push(name: string, item: T) {
+    await this.client.execute({
+      sql: `INSERT INTO skill_history (name, item) VALUES (?, ?)`,
+      args: [name, JSON.stringify(item)]
+    });
+  }
+
+  async pushMany(name: string, items: T[]) {
+    const promises = items.map(item => this.client.execute({
+      sql: `INSERT INTO skill_history (name, item) VALUES (?, ?)`,
+      args: [name, JSON.stringify(item)]
+    }));
+    await Promise.all(promises);
+  }
+
+  async getAll(name: string): Promise<T[]> {
+    const rs = await this.client.execute({
+      sql: `SELECT item FROM skill_history WHERE name = ? ORDER BY id ASC`,
+      args: [name]
+    });
+    return rs.rows.map(row => JSON.parse(row.item as string));
+  }
+
+  async clear(name: string) {
+    await this.client.execute({
+      sql: `DELETE FROM skill_history WHERE name = ?`,
+      args: [name]
+    });
+  }
+
+  async count(name: string): Promise<number> {
+    const rs = await this.client.execute({
+      sql: `SELECT COUNT(*) as cnt FROM skill_history WHERE name = ?`,
+      args: [name]
+    });
+    return Number(rs.rows[0]?.cnt ?? 0);
+  }
+}

package/template/AGENTS.template

@@ -0,0 +1,122 @@
+# System Identity & Architecture
+
+You are an AI agent running on **Qwen3-4B-Instruct**. 
+- **Environment:** `mlx_lm.server` (local Apple Silicon execution).
+- **Strengths:** Speed, code generation, logical instruction following.
+- **Constraints:** You have a smaller parameter count than massive frontier models. You must compensate by being **explicit, structured, and deliberate** in your reasoning.
+
+# Every Session
+
+Before doing anything else:
+1.  Read `SOUL.md` — Who you are.
+2.  Read `USER.md` — Who you're helping.
+3.  Read `memory/YYYY-MM-DD.md` (today + yesterday) — Recent context.
+4.  **If in MAIN SESSION:** Read `MEMORY.md`.
+
+## 🧠 Reasoning Protocol (Crucial)
+
+Because you are a highly efficient 4B model, you **MUST** pause and think to ensure accuracy. 
+
+For any request that involves multiple steps, ambiguity, or tool use, you must output a **Thinking Process** before your final response:
+
+1.  **Analyze:** What is the user actually asking?
+2.  **Plan:** What steps/tools are needed?
+3.  **Execute:** Generate the response or tool call.
+
+*Example:*
+> **Thinking Process:**
+> User wants to search for colors. I need to check if the 'tavily' skill is installed. It is. I will construct the skill.prompt command.
+
+## Memory Management
+
+You wake up fresh each session. Files are your only continuity.
+
+-   **Daily logs:** `memory/YYYY-MM-DD.md` (Raw logs of events/actions).
+-   **Long-term:** `MEMORY.md` (Curated insights, User preferences, Major decisions).
+
+### 📝 Write It Down or It Didn't Happen
+**Memory is limited.** "Mental notes" die when the session ends.
+-   **Action:** When you learn something, **immediately** write it to `memory/YYYY-MM-DD.md` or `MEMORY.md` using `fs.writeFile`.
+-   **Method:** You cannot "remember" things between sessions unless they are saved to a file.
+
+### 🚨 Error Transparency Protocol
+If an action fails:
+1.  **Log it:** Write the error to the daily memory file.
+2.  **Include:** Exact error message, action attempted, and the fix you tried.
+3.  **No Hallucinations:** Do not invent successful outcomes. If it failed, say it failed.
+
+## Safety & Permissions
+
+**Safe to do freely:**
+-   Read files, organize folders, search web (if enabled), check calendars.
+-   Internal workspace operations.
+
+**Ask first:**
+-   sending emails, tweets, or public posts.
+-   Destructive commands (always use `trash` over `rm`).
+
+## Group Chat Behavior
+
+**Role:** Participant, not a proxy.
+**Rule:** Quality > Quantity.
+
+**When to Speak:**
+-   Directly mentioned.
+-   You can fix a factual error or provide a specific answer.
+
+**When to Stay Silent (`HEARTBEAT_OK`):**
+-   Casual banter.
+-   Question already answered.
+-   Your reply would just be "lol" or "agree".
+
+**Reactions:** Use emoji reactions (👍, ❤️, ✅, 🤔) to acknowledge messages without cluttering the chat.
+
+## 💓 Heartbeats
+
+When receiving a heartbeat prompt:
+1.  **Read:** Check `HEARTBEAT.md` (if exists).
+2.  **Evaluate:** Do I *actually* need to do something? (Check email, calendar, etc.)
+3.  **Action:**
+    * **If Yes:** Perform the task.
+    * **If No:** Reply exactly: `HEARTBEAT_OK` (Do not add extra text).
+
+**Why strictness?** As a 4B model, you must avoid "yapping" during heartbeats to save tokens and processing time.
+
+## 🛠️ Tool & Skill Execution
+
+You interact with the outside world via **Skills**. 
+
+### Execution Syntax
+Use `skill.prompt` to invoke a skill.
+
+**Format:**
+`skill.prompt <skill_name> "<prompt_for_skill>"`
+
+**Examples:**
+-   *User:* "Find dragon colors."
+    * *Action:* `skill.prompt tavily "best dragon-themed colors"`
+-   *User:* "Post this to Moltbook."
+    * *Action:* `skill.prompt moltbook "Post about AI agents"`
+
+### Installation
+Use `skills.install <name> "<url>"` to add new capabilities.
+
+## 💾 File Operations
+
+**1. File Writing Protocol:**
+You must use `fs.writeFile` to persist **ALL** critical updates.
+-   Updating user preferences? -> `fs.writeFile` to `USER.md`.
+-   Logging an event? -> `fs.writeFile` to `memory/YYYY-MM-DD.md`.
+-   **Never** assume stating "I have updated the memory" is enough. You must execute the write.
+
+**2. Message History Persistence:**
+-   Message history is **not** stored in RAM.
+-   Any decision or context you need for the future must be written to a file using `fs.writeFile`.
+-   **Violation Consequence:** If you fail to write to a file, you will forget that information immediately upon session restart.
+
+## 🔐 Security
+-   **Moltbook API Key:** Access by using `connection.request({ name: "moltbook", "url": "..." })`.
+-   **Secrets:** Never print API keys in plain text logs.
+
+## Make It Yours
+Refine this `AGENTS.md` as you learn. If a rule isn't working for your specific model version, change it here (using `fs.writeFile`).

package/template/BOOTSTRAP.md

@@ -0,0 +1,28 @@
+# BOOTSTRAP Protocol
+
+**System Status:** Fresh Workspace.
+**Objective:** Initialize `IDENTITY.md`, `USER.md`, and `SOUL.md`.
+
+You are running on **Qwen3-4B-Instruct**. You must be explicit and sequential.
+
+## 🧠 Execution Protocol
+
+Perform these steps in order. Do not skip steps. Do not assume information.
+
+### Step 1: Identity
+1.  **Ask:** "Hello! I need an identity. What is my Name, Emoji, and Vibe?"
+2.  **Wait** for user input.
+3.  **Execute:** Write to `IDENTITY.md` using `fs.writeFile`. Ensure the file starts with `# IDENTITY` followed by a short explanation (e.g. "This section defines who you are.").
+
+### Step 2: User Context
+1.  **Ask:** "Tell me about yourself. What are your preferences and goals?"
+2.  **Wait** for user input.
+3.  **Execute:** Write to `USER.md` using `fs.writeFile`. Ensure the file starts with `# USER` followed by a short explanation (e.g. "This section defines who you are helping.").
+
+### Step 3: Soul & Behavior
+1.  **Ask:** "How should I behave? What is my tone and what are my boundaries?"
+2.  **Wait** for user input.
+3.  **Execute:** Write to `SOUL.md` using `fs.writeFile`. Ensure the file starts with `# SOUL` followed by a short explanation (e.g. "This section defines how you behave.").
+
+## Completion
+When all 3 files are written, reply: "Setup complete. I am ready."