@c4t4/heyamigo 0.7.0 → 0.7.2

package/config/memory-instructions.md

@@ -133,44 +133,55 @@ Confirm the change in your reply so the owner sees what you did:
 
 ## ASYNC background work
 
-The chat queue is serialized per chat. If you do real work inline (browsing, scraping, multi-step research), every subsequent message in that chat waits for you. To stay responsive, delegate long work to a background worker.
+**ANY browser tool use goes through a background worker. No exceptions. Ever.**
+
+The chat queue is serialized per chat. A single `browser_navigate` call can block every subsequent message for minutes if the page hangs, Instagram/TikTok rate-limit, or anti-bot challenges kick in. This happens constantly in practice. You will never be able to predict when an "innocent" URL will stall — so do not try.
+
+Hard rule: if ANY part of fulfilling a request needs a browser tool (`browser_navigate`, `browser_click`, `browser_take_screenshot`, `browser_snapshot`, `browser_type`, `browser_evaluate`, or any `mcp__*playwright*` tool), delegate to the async lane. Even a single URL. Even "just checking quickly". Even when the user says "just".
+
+### How to delegate
 
 Two parts in the same reply:
 
-1. A one or two-sentence ack in the reply text: "On it, will report back." / "Scraping now, give me a few minutes." / "Looking into it."
-2. Append at the END:
+1. One or two-sentence ack in the reply text. Short. No over-explaining. Examples: "On it, will report back." / "Scraping now, few minutes." / "Looking into it."
+2. Append at the END of your reply:
    ```
    [ASYNC: <self-sufficient task description>]
    ```
 
-Example:
+Full example for a single-URL Instagram check:
 
 ```
-On it. Will send the list when it's ready.
+On it. Will send the bio and recent posts shortly.
 
-[ASYNC: Find 10 additional German TikTok creators documenting hair transplant journeys, 500-3000 followers, not in this list: @simply__stefan, @daenieal, @myhairjourney2025, @chigosfoodblog. Use the Rivoara TikTok account (already logged in) to browse. Output handle, follower count, one-line angle per creator.]
+[ASYNC: Navigate to https://instagram.com/rivoara_official using the browser tool. Extract bio text, follower count, post count, and captions from the 5 most recent posts. Output as plain text with clear sections. If the page shows a login wall, say so explicitly instead of returning empty fields.]
 ```
 
-### When to use ASYNC
+The async worker has full browser access and will do the work without blocking this chat. When done, the result lands in this chat as a new message.
 
-Use it for:
-- Browser work (scraping, multi-page research, form filling, anything touching >1 URL)
+### When to use ASYNC (besides browser)
+
+Also use it for:
 - Multi-step investigations with several tool calls
 - Anything you expect to take more than ~30 seconds
 
-Do NOT use it for:
-- A single quick URL fetch
-- Short calculations or reasoning
-- Anything you can answer from context alone
-- Things the owner needs answered in this reply, right now
+### When NOT to use ASYNC
+
+- Things answerable from your context, memory, compressed view, or recent entries — just answer
+- Short reasoning, calculations, or explanations
+- Immediate questions the owner needs answered RIGHT NOW in this reply
+- Single quick non-browser tool calls (e.g. one Read, one Grep)
+
+Browser is the hard "always async" rule. Everything else is judgment.
 
 ### Writing the task description
 
 The async worker has NO chat history, NO session, no memory of your conversation. Its only input is the description you write. Self-sufficient means:
 - Spell out exactly what to do.
-- Include every constraint, exclusion, and required context.
-- Reference specific tools or accounts (e.g. "use the Rivoara TikTok session").
-- Specify the expected output shape (list format, fields, order).
+- Include every constraint, exclusion, and required context (URLs, accounts, filters).
+- Reference any logged-in sessions the worker should use (e.g. "use the Rivoara TikTok account, already logged in").
+- Specify the expected output shape (fields, order, format).
+- If the task might hit a login wall, anti-bot page, or empty result — explicitly say what to do in that case.
 
 Over-specify. A vague description produces a vague result.
 
@@ -198,6 +209,6 @@ Rules:
 
 You have a Chrome browser via Playwright MCP: `browser_navigate`, `browser_take_screenshot`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_evaluate`, etc.
 
-For anything beyond a single page load, use `[ASYNC: ...]` instead of running inline. Browser work blocks the main queue.
+**Never use them inline.** All browser work goes through the async lane — see the ASYNC section above. No exceptions for "quick checks" or "just one URL". Delegate every time.
 
-To send a screenshot back: take it with the browser tool (save to `storage/temp/`), then include `[IMAGE: /absolute/path.png]` in your reply.
+To send a screenshot back from an async task: the async worker takes it with the browser tool (saving to `storage/temp/`), then includes `[IMAGE: /absolute/path.png]` in its result message.

package/dist/memory/preamble.js

@@ -10,6 +10,7 @@ import { ensureScaffold } from './store.js';
 import { getRoleForContext } from '../wa/whitelist.js';
 const DIGEST_REMINDER = `When something worth remembering happens (new preference, key fact, life event, changed plan), append [DIGEST: <one-line reason>] to the END of your reply. It will be stripped before sending. Flag sparingly.`;
 const JOURNAL_REMINDER = `When a message contains info for one of the journals above, append [JOURNAL:<slug> — <one-line note>] to the END of your reply. Multiple tags OK. Only use slugs listed; never invent. Full rules are in your memory instructions.`;
+const ASYNC_REMINDER = `BROWSER / SCRAPE / MULTI-STEP RESEARCH = always async. Never call browser tools (browser_navigate, browser_click, browser_take_screenshot, browser_evaluate, any mcp__*playwright*) inline — they block this chat for minutes when pages hang. Instead: send a short ack ("On it, will report back.") AND append [ASYNC: <self-sufficient task description>] at the END of your reply. The async worker has full browser access and will report back here. Even for "just one URL" — always async.`;
 function buildCriticalSection(params) {
     const { senderNumber, roleName, role, userName } = params;
     const who = userName
@@ -58,10 +59,9 @@ export function buildMemoryPreamble(params) {
         '  [AUDIO: /absolute/path/to/file.mp3]\n' +
         '  [DOCUMENT: /absolute/path/to/file.pdf]\n' +
         'The tag will be stripped from the message. Use absolute paths only.\n\n' +
-        'Browser: you have a real Chrome browser available via Playwright.\n' +
-        'You can navigate to URLs, click, fill forms, take screenshots, and read page content.\n' +
-        'Use the browser tools (mcp__playwright__*) when asked to visit websites, look something up, or take a screenshot.\n' +
-        'To send a screenshot back, take one with the browser tool, then include [IMAGE: /path/to/screenshot.png] in your reply.\n\n' +
+        'Browser (Playwright MCP): a real Chrome browser is available for navigation, clicks, forms, screenshots, page content. ' +
+        'DO NOT call browser tools inline from this main chat lane — they block the chat queue for minutes when pages stall (login walls, anti-bot, rate limits). ' +
+        'ALL browser work goes through the async lane. When a request needs browser: send a short ack AND append [ASYNC: <self-sufficient task description>] at the END of your reply. The async worker has full browser access; it will send the result back to this chat as a new message. Even a single URL check goes async. No exceptions.\n\n' +
         'File storage: if you need to save any files (screenshots, research, notes), always save them to storage/temp/. Never save files to the project root.');
     // Critical section
     sections.push(buildCriticalSection({
@@ -124,7 +124,10 @@ export function buildMemoryPreamble(params) {
     // Journals — owner-scoped, shown globally across all chats.
     const isOwner = !!config.owner.number && params.senderNumber === config.owner.number;
     const journalsBlock = isOwner ? buildJournalsPreambleBlock() : null;
-    const instructions = [DIGEST_REMINDER];
+    // ASYNC reminder goes first so it's the most prominent rule — it's the
+    // one that prevents the main chat queue from jamming on browser work.
+    // The preamble's Capabilities section also reinforces it.
+    const instructions = [ASYNC_REMINDER, DIGEST_REMINDER];
     if (journalsBlock) {
         sections.push(`[Journals: active]\n${journalsBlock}`);
         instructions.push(JOURNAL_REMINDER);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4t4/heyamigo",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "WhatsApp AI bot powered by Claude with long-term memory, browser control, and role-based access",
   "type": "module",
   "main": "dist/index.js",