clawlet 0.5.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawlet",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "A lightweight AI based personal assistant.",
   "main": "src/cli.ts",
   "type": "module",

package/src/agent.eval.test.ts

@@ -217,6 +217,7 @@ describe('Agent Evals (LLM)', () => {
   it(`reasoning_multi_step`, async () => runTestCaseFile('reasoning_multi_step.yaml'), EVAL_TIMEOUT);
   it(`refactoring_edit`, async () => runTestCaseFile('refactoring_edit.yaml'), EVAL_TIMEOUT);
   it(`skill_sandbox_execution`, async () => runTestCaseFile('skill_sandbox_execution.yaml'), EVAL_TIMEOUT);
+  it(`rewrite_agents_md`, async () => runTestCaseFile('rewrite_agents_md.yaml'), EVAL_TIMEOUT);
   it(`skill_system_installation`, async () => runTestCaseFile('skill_system_installation.yaml'), EVAL_TIMEOUT);
   it(`soft_delete`, async () => runTestCaseFile('soft_delete.yaml'), EVAL_TIMEOUT);
   it(`stat_check`, async () => runTestCaseFile('stat_check.yaml'), EVAL_TIMEOUT);

package/src/agent.ts

@@ -16,9 +16,6 @@ import { createTools } from './tools.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const GENERATE_TEXT_TEMPERATURE = 0.6;
-const GENERATE_TEXT_TOP_P = 0.95;
-const GENERATE_TEXT_MAX_OUTPUT_TOKENS = 16384;
 const GENERATE_TEXT_MAX_STEPS = 30;
 
 // --- ADAPTER INTERFACES ---
@@ -138,9 +135,6 @@ async function runAgent(
       system: await buildSystemPrompt(memory),
       messages,
       tools,
-      temperature: GENERATE_TEXT_TEMPERATURE,
-      topP: GENERATE_TEXT_TOP_P,
-      maxOutputTokens: GENERATE_TEXT_MAX_OUTPUT_TOKENS,
       stopWhen: stepCountIs(GENERATE_TEXT_MAX_STEPS),
 
       onStepFinish: (step) => {

package/src/evals/rewrite_agents_md.yaml

@@ -0,0 +1,161 @@
+name: "Extend AGENTS.md with New Section"
+description: "Tests whether the agent can read a large AGENTS.md, append a new section, and preserve the existing content. Stresses the model's ability to handle long text read+write cycles."
+
+timeout: 240000
+
+setup:
+  files:
+    SOUL.md: |
+      # SOUL
+      I amlike what I do.
+    USER.md: |
+      # USER
+      name: Mr. X.
+    IDENTITY: |
+      # IDENTITY
+      name: Bob
+    AGENTS.md: |
+      # 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).
+
+      ## 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>"`
+
+      ### 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`.
+
+      ## 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 by using `fs.writeFile`.
+
+input: "Add a new section at the end called '## Daily Reflection Protocol' to the file AGENTS.md (use the tool fs.writeFile). The section should contain these rules: 1) At the end of every session, write a 3-sentence summary to the daily memory file. 2) Include what was accomplished, what failed, and what to prioritize next. 3) Tag entries with #reflection for easy searching. Make sure you preserve ALL existing content in AGENTS.md when writing the updated version."
+
+validate:
+  files:
+    AGENTS.md:
+      contains:
+        - "System Identity"
+        - "Every Session"
+        - "Reasoning Protocol"
+        - "Memory Management"
+        - "Safety & Permissions"
+        - "Daily Reflection Protocol"
+        - "#reflection"
+      contains_any:
+        - "3-sentence"
+        - "three-sentence"
+        - "summary"
+        - "reflection"
+      must_not_contain:
+        - "[object Object]"
+  response:
+    must_not_contain:
+      - "<tool_call>"
+    contains_any:
+      - "AGENTS.md"
+      - "added"
+      - "updated"
+      - "section"
+      - "reflection"
+      - "Daily Reflection"

package/src/llm.ts

@@ -1,10 +1,10 @@
 import { hermesToolMiddleware, xmlToolMiddleware, yamlToolMiddleware } from "@ai-sdk-tool/parser";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
-import { addToolInputExamplesMiddleware, extractReasoningMiddleware, wrapLanguageModel, type LanguageModel, gateway } from "ai";
+import { addToolInputExamplesMiddleware, extractReasoningMiddleware, wrapLanguageModel, type LanguageModel, gateway, defaultSettingsMiddleware, type LanguageModelMiddleware } from "ai";
 
 const OPENAI_COMPATIBLE_MODEL_ID = process.env.OPENAI_COMPATIBLE_MODEL_ID ?? 'qwen-local';
 const OPENAI_COMPATIBLE_BASE_URL = process.env.OPENAI_COMPATIBLE_BASE_URL ?? 'http://localhost:8000/v1';
-const AI_GATEWAY_USE_QWEN_MIDDLEWARE = process.env.AI_GATEWAY_USE_QWEN_MIDDLEWARE ?? '';
+const AI_GATEWAY_USE_QWEN_MIDDLEWARE = process.env.AI_GATEWAY_USE_QWEN_MIDDLEWARE ?? (!process.env.AI_GATEWAY_MODEL_ID ? '1' : '');
 
 // --- MODEL SETUP ---
 const localProvider = createOpenAICompatible({
@@ -12,24 +12,28 @@ const localProvider = createOpenAICompatible({
   baseURL: OPENAI_COMPATIBLE_BASE_URL,
 });
 
-export const model : LanguageModel = process.env.AI_GATEWAY_MODEL_ID ? (AI_GATEWAY_USE_QWEN_MIDDLEWARE ? wrapLanguageModel({
-  model: gateway(process.env.AI_GATEWAY_MODEL_ID),
-  middleware: [
-    hermesToolMiddleware,
-    //xmlToolMiddleware,
-    addToolInputExamplesMiddleware({  prefix: 'Input Examples:', }),
-    extractReasoningMiddleware({
-      tagName: "think"
-    })
-  ]
-}) : process.env.AI_GATEWAY_MODEL_ID) : wrapLanguageModel({
-  model: localProvider.languageModel(OPENAI_COMPATIBLE_MODEL_ID),
-  middleware: [
-    hermesToolMiddleware,
-    //xmlToolMiddleware,
-    addToolInputExamplesMiddleware({  prefix: 'Input Examples:', }),
-    extractReasoningMiddleware({
-      tagName: "think"
-    })
-  ]
+const unwrappedModel : LanguageModel = process.env.AI_GATEWAY_MODEL_ID ? gateway.languageModel(process.env.AI_GATEWAY_MODEL_ID) : localProvider.languageModel(OPENAI_COMPATIBLE_MODEL_ID);
+
+const middleware : LanguageModelMiddleware[] = [
+  defaultSettingsMiddleware({
+    settings: {
+      // tool calls: temperature: 0.0, maxOutputTokens: 2048
+      // normal chat: topP: 0.8, maxOutputTokens: 2048
+      // no tools:
+      topP: 0.9, maxOutputTokens: 8192
+    },
+  })
+];
+
+if (AI_GATEWAY_USE_QWEN_MIDDLEWARE) {
+  middleware.push(hermesToolMiddleware);
+  middleware.push(addToolInputExamplesMiddleware({  prefix: 'Input Examples:', }));
+  middleware.push(extractReasoningMiddleware({
+    tagName: "think"
+  }));
+}
+
+export const model : LanguageModel = wrapLanguageModel({
+  model: unwrappedModel,
+  middleware
 });

package/src/logger.ts

@@ -1,5 +1,7 @@
+import 'dotenv/config';
 import pino from "pino";
 
+const isTest = process.env.NODE_ENV === "test";
 const isProd = process.env.NODE_ENV === "production";
 const logFile = process.env.LOG_FILE_PATH ?? `${process.cwd()}/logs/clawlet.jsonl`;
 
@@ -18,7 +20,26 @@ const transport = pino.transport({
   ]
 });
 
-export const logger = pino({
+export const logger = isTest ? pino(
+  {
+    base: {
+      service: process.env.SERVICE_NAME ?? "clawlet",
+      env: process.env.NODE_ENV ?? "development",
+      version: process.env.APP_VERSION,
+    },
+    timestamp: () => `,"ts":"${new Date().toISOString()}"`,
+    formatters: {
+      level(label, number) {
+        return { level: number, level_label: label };
+      },
+    },
+    level: 'debug', 
+  },
+  pino.destination({
+    dest: 1,     
+    sync: true   
+  })
+) : pino({
     level: process.env.LOG_LEVEL ?? (isProd ? "info" : "debug"),
     base: {
       service: process.env.SERVICE_NAME ?? "clawlet",

package/src/tools.ts

@@ -14,9 +14,6 @@ import TurndownService from 'turndown';
 import { logger } from './logger.js';
 
 // Resolve the package root directory (where template/ lives), independent of cwd
-const GENERATE_TEXT_TEMPERATURE = 0.6;
-const GENERATE_TEXT_TOP_P = 0.95;
-const GENERATE_TEXT_MAX_OUTPUT_TOKENS = 16384;
 const GENERATE_TEXT_MAX_STEPS = 30;
 
 const turndownService = new TurndownService()
@@ -488,6 +485,27 @@ export function createTools(memory: AgentMemory, model: LanguageModel) {
       }
     }),
 
+    'fs.appendFile': tool({
+      description: 'Apped specific string to a file (will create it if it does not exist yet). Use this for appending something to daily memory files and the likes.',
+      inputSchema: jsonSchema<{ path: string, find: string, replace: string }>({
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Path/key of the file to edit' },
+          content: { type: 'string', description: 'The new text to append to the file.' },
+        },
+        required: ['path', 'content'],
+      }),
+      execute: async ({ path, find, replace }) => {
+        logger.debug({ path }, 'FS appendFile');
+        try {
+          const content = await memory.workspace.getItem(path);
+          const fileText = String(content || '');
+          await memory.workspace.setItem(path, (fileText != '' ? (fileText + "\n") : '') + content);
+          return `Success: Appended "${path}".`;
+        } catch (e: any) { return "Error appending file: " + e.message; }
+      }
+    }),
+
     'fs.delete': tool({
       description: 'Delete a file. If the file is outside .trash/, it is moved to .trash/ (soft delete). If the file is already inside .trash/, it is permanently removed.',
       inputSchema: jsonSchema<{ path: string }>({
@@ -940,6 +958,20 @@ Return ONLY a JSON object mapping tool names to arrays of permission rules. Exam
           }
         ];
 
+        skillPermissions['fs.appendFile'] = skillPermissions['fs.appendFile'] || [
+          {
+            path: "memory/*",
+            allowed: "1"
+          }
+        ];
+
+        skillPermissions['fs.editFile'] = skillPermissions['fs.editFile'] || [
+          {
+            path: "memory/*",
+            allowed: "1"
+          }
+        ];
+
         skillPermissions['fs.readFile'] = skillPermissions['fs.readFile'] || [
           {
             path: "memory/*",
@@ -972,9 +1004,6 @@ Return ONLY a JSON object mapping tool names to arrays of permission rules. Exam
             system: await buildSkillSystemPrompt(name, memory, skillPermissions),
             messages,
             tools: Object.keys(sandboxed).length > 0 ? sandboxed : {},
-            temperature: GENERATE_TEXT_TEMPERATURE,
-            topP: GENERATE_TEXT_TOP_P,
-            maxOutputTokens: GENERATE_TEXT_MAX_OUTPUT_TOKENS,
             stopWhen: stepCountIs(GENERATE_TEXT_MAX_STEPS),
             onStepFinish: (step) => {
               if (step.toolCalls.length > 0) {

package/template/AGENTS.template

@@ -36,7 +36,7 @@ You wake up fresh each session. Files are your only continuity.
 
 ### 📝 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`.
+-   **Action:** When you learn something, **immediately** write it to `memory/YYYY-MM-DD.md` by using `fs.appendFile` or `MEMORY.md` using `fs.writeFile` or `fs.editFile`.
 -   **Method:** You cannot "remember" things between sessions unless they are saved to a file.
 
 ### 🚨 Error Transparency Protocol
@@ -105,13 +105,13 @@ Use `skills.install <name> "<url>"` to add new capabilities.
 
 **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`.
+-   Updating user preferences? -> `fs.writeFile` or `fs.editFile` to `USER.md`.
+-   Logging an event? -> `fs.appendFile` or `fs.editFile` 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`.
+-   Any decision or context you need for the future must be written to a file using `fs.writeFile` or `fs.editFile`.
 -   **Violation Consequence:** If you fail to write to a file, you will forget that information immediately upon session restart.
 
 ## 🔐 Security
@@ -119,4 +119,4 @@ You must use `fs.writeFile` to persist **ALL** critical updates.
 -   **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.editFile` or read only part of the file to avoid exceeding token limits).
+Refine this `AGENTS.md` as you learn. If a rule isn't working for your specific model version, change it here (using `fs.editFile` or add a section using `fs.appendFile` or read only part of the file to avoid exceeding token limits).