@c4t4/heyamigo 0.1.17 → 0.3.0

package/config/memory-instructions.md

@@ -23,6 +23,87 @@ Do NOT flag for:
 
 The marker will be stripped from your reply before the person sees it. It is a private signal to trigger profile/brief updates.
 
+## Journals
+
+A **journal** is a long-running tracking project the owner sets up (e.g. a health journal, a dog-training log, a work-wins log). Journals are how you help the owner keep track of recurring topics without them having to log things manually each time.
+
+The list of the owner's active journals appears in your preamble under `[Journals: active]` with the slug and a short purpose line. Journals are owner-scoped and global — the same list applies across every chat and session the owner is in.
+
+### When to flag a journal entry
+
+When a message contains info that belongs in one of the active journals, append a marker to the END of your reply:
+
+```
+[JOURNAL:<slug> — <one-line note>]
+```
+
+You can include multiple journal tags in one reply if multiple journals are relevant. You can combine `[DIGEST: ...]` and `[JOURNAL: ...]` in the same reply — they are independent. Order doesn't matter as long as all tags are at the end.
+
+Separator between slug and note can be em-dash, en-dash, hyphen, or colon.
+
+Examples (assuming `health` and `training` are active slugs):
+
+- Owner: "slept 5hrs, mild headache again"
+  Reply ends with: `[JOURNAL:health — 5hrs sleep, mild headache]`
+
+- Owner: "Biscuit finally learned 'stay' for 30 seconds today!"
+  Reply ends with: `[JOURNAL:training — Biscuit held 'stay' for 30s]`
+
+- Owner: "slept well, 8hrs, and Biscuit did great on the walk"
+  Reply ends with: `[JOURNAL:health — 8hrs sleep, rested] [JOURNAL:training — good leash walk]`
+
+### Hard rules
+
+- **Only use slugs that appear in `[Journals: active]`.** If the owner mentions something relevant to a topic but no journal exists for it, do not invent a slug. Suggest creating a journal instead.
+- **Don't flag unrelated content.** A message about dinner isn't a health-journal entry unless the owner explicitly connects it to health.
+- **Don't flag every message.** Flag when there's real content for the journal. Chit-chat is not an entry.
+- **Don't invent entries.** If the owner said something ambiguous, ask them to clarify before flagging.
+
+### Proactive engagement in-conversation
+
+Journals exist to keep the owner engaged over time. When you're responding and a journal is relevant, you may:
+
+- Ask a clarifying follow-up if an entry is vague ("how bad was the headache, 1-10?").
+- Reference a recent entry when useful ("last time you logged 5hrs sleep you also had a headache, same pattern?").
+- Offer to check in: "want me to ask about sleep tomorrow night?"
+
+Don't spam. One small nudge at a time, natural to the conversation. Never drag journal topics into a thread about something unrelated. Scheduled check-ins are handled separately by the system; your role here is in-conversation.
+
+### Setting up a new journal
+
+When the owner says something like "start a health journal":
+
+1. Propose a concrete purpose in one short message:
+   > "Health journal: tracking sleep, symptoms, meds, mood. Daily check-in at 21:00, nudge if silent 3 days. Sound right?"
+2. Wait for confirmation or edits.
+3. Once confirmed, create it by appending this marker to the END of your reply:
+   ```
+   [JOURNAL-NEW:<slug> — <one-line purpose>]
+   ```
+   The marker will be stripped. The journal is created immediately and becomes active. You can flag the first entry in the same reply by also adding a `[JOURNAL:<slug> — <note>]` right after.
+
+Example end of reply:
+```
+[JOURNAL-NEW:health — Track sleep, symptoms, meds, mood]
+[JOURNAL:health — 5hrs sleep, mild headache]
+```
+
+Slug rules: lowercase letters, digits, hyphens. Max 48 chars. Must start with a letter or digit.
+
+Be opinionated about the purpose. Don't ask ten questions; pick reasonable defaults and let them tweak.
+
+### Pausing, resuming, archiving
+
+The owner can also ask you to pause/archive/resume a journal. Emit one of these markers:
+
+```
+[JOURNAL-PAUSE:<slug>]
+[JOURNAL-RESUME:<slug>]
+[JOURNAL-ARCHIVE:<slug>]
+```
+
+Do this only when the owner asks. Never pause or archive a journal on your own judgment.
+
 ## Browser and screenshots
 
 You have access to a Chrome browser via tools: browser_navigate, browser_take_screenshot, browser_snapshot, browser_click, browser_type, browser_evaluate, and more.

package/dist/cli/index.js

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { Command } from 'commander';
+const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json');
+const pkgVersion = JSON.parse(readFileSync(pkgPath, 'utf-8')).version;
 const program = new Command();
 program
     .name('heyamigo')
     .description('WhatsApp AI Bot powered by Claude')
-    .version('0.1.0');
+    .version(pkgVersion);
 program
     .command('setup')
     .description('Run the setup wizard')

package/dist/gateway/commands.js

@@ -1,6 +1,7 @@
 import { clearSession, getSessionInfo } from '../ai/sessions.js';
 import { reloadSystemPrompt } from '../ai/claude.js';
 import { config } from '../config.js';
+import { createJournal, getJournal, isValidSlug, listJournals, readEntries, snoozeJournal, updateJournalStatus, } from '../memory/journals.js';
 import { runDigestNow } from '../memory/scheduler.js';
 import { sendText } from '../wa/sender.js';
 export async function tryCommand(ctx) {
@@ -54,5 +55,199 @@ export async function tryCommand(ctx) {
         }).catch(() => undefined);
         return true;
     }
+    if (cmd === 'journal' || cmd === 'journals') {
+        if (!isOwner(ctx.senderNumber)) {
+            await sendText(ctx.sock, ctx.jid, 'Journals are owner-only.', ctx.quoted);
+            return true;
+        }
+        const rest = trimmed.slice(prefix.length + cmd.length).trim();
+        await handleJournalCmd(ctx, rest);
+        return true;
+    }
+    if (cmd === 'snooze') {
+        if (!isOwner(ctx.senderNumber)) {
+            await sendText(ctx.sock, ctx.jid, 'Snooze is owner-only.', ctx.quoted);
+            return true;
+        }
+        const rest = trimmed.slice(prefix.length + cmd.length).trim();
+        await handleSnoozeCmd(ctx, rest);
+        return true;
+    }
     return false;
 }
+async function handleSnoozeCmd(ctx, rest) {
+    const [slugRaw, durationRaw] = rest.split(/\s+/);
+    const slug = (slugRaw ?? '').toLowerCase();
+    const duration = (durationRaw ?? '24h').toLowerCase();
+    if (!slug) {
+        await sendText(ctx.sock, ctx.jid, 'Usage: /snooze <slug> [duration]\nDuration: e.g. 6h, 2d (default 24h)', ctx.quoted);
+        return;
+    }
+    if (!getJournal(slug)) {
+        await sendText(ctx.sock, ctx.jid, `No journal "${slug}".`, ctx.quoted);
+        return;
+    }
+    const secs = parseDuration(duration);
+    if (!secs) {
+        await sendText(ctx.sock, ctx.jid, `Bad duration "${duration}". Use formats like 6h, 2d, 30m.`, ctx.quoted);
+        return;
+    }
+    const until = Math.floor(Date.now() / 1000) + secs;
+    snoozeJournal(slug, until);
+    await sendText(ctx.sock, ctx.jid, `Snoozed "${slug}" for ${duration}. No nudges until ${new Date(until * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC.`, ctx.quoted);
+}
+function parseDuration(raw) {
+    const m = raw.match(/^(\d+)\s*([mhd])$/);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const u = m[2];
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    if (u === 'm')
+        return n * 60;
+    if (u === 'h')
+        return n * 3600;
+    if (u === 'd')
+        return n * 86400;
+    return null;
+}
+function isOwner(senderNumber) {
+    return !!config.owner.number && senderNumber === config.owner.number;
+}
+async function handleJournalCmd(ctx, rest) {
+    const [subRaw, ...argParts] = rest.split(/\s+/);
+    const sub = (subRaw ?? 'list').toLowerCase();
+    const args = argParts.join(' ').trim();
+    if (sub === 'list' || sub === '') {
+        const journals = listJournals();
+        if (journals.length === 0) {
+            await sendText(ctx.sock, ctx.jid, 'No journals yet. Create one with:\n/journal create <slug> <purpose>', ctx.quoted);
+            return;
+        }
+        const lines = ['Journals:'];
+        for (const j of journals) {
+            lines.push(`- ${j.slug} [${j.status}]: ${j.purpose || j.name}`);
+        }
+        await sendText(ctx.sock, ctx.jid, lines.join('\n'), ctx.quoted);
+        return;
+    }
+    if (sub === 'create' || sub === 'new') {
+        const [slugRaw, ...purposeParts] = args.split(/\s+/);
+        const slug = (slugRaw ?? '').toLowerCase();
+        const purpose = purposeParts.join(' ').trim();
+        if (!slug || !purpose) {
+            await sendText(ctx.sock, ctx.jid, 'Usage: /journal create <slug> <purpose>\nExample: /journal create health Track sleep, symptoms, meds, mood', ctx.quoted);
+            return;
+        }
+        if (!isValidSlug(slug)) {
+            await sendText(ctx.sock, ctx.jid, `Invalid slug "${slug}". Use lowercase letters, digits, hyphens. Max 48 chars.`, ctx.quoted);
+            return;
+        }
+        if (getJournal(slug)) {
+            await sendText(ctx.sock, ctx.jid, `Journal "${slug}" already exists.`, ctx.quoted);
+            return;
+        }
+        try {
+            const j = createJournal({
+                slug,
+                name: titleCase(slug),
+                purpose,
+            });
+            await sendText(ctx.sock, ctx.jid, `Journal "${j.slug}" created and active. I'll start tagging relevant entries. Use /journal show ${j.slug} to inspect.`, ctx.quoted);
+        }
+        catch (err) {
+            await sendText(ctx.sock, ctx.jid, `Create failed: ${err.message}`, ctx.quoted);
+        }
+        return;
+    }
+    if (sub === 'show' || sub === 'info') {
+        const slug = args.split(/\s+/)[0]?.toLowerCase() ?? '';
+        const j = getJournal(slug);
+        if (!j) {
+            await sendText(ctx.sock, ctx.jid, `No journal "${slug}".`, ctx.quoted);
+            return;
+        }
+        const lines = [
+            `${j.name} (${j.slug}) [${j.status}]`,
+            j.purpose,
+        ];
+        if (j.fields.length)
+            lines.push(`Fields: ${j.fields.join(', ')}`);
+        if (j.cadence.checkin)
+            lines.push(`Check-in: ${j.cadence.checkin}`);
+        if (j.cadence.followup_after)
+            lines.push(`Follow-up after: ${j.cadence.followup_after}`);
+        if (j.cadence.nudge_if_silent)
+            lines.push(`Nudge if silent: ${j.cadence.nudge_if_silent}`);
+        const entries = readEntries(j.slug, 5);
+        if (entries.length) {
+            lines.push('', 'Recent entries:');
+            for (const e of entries) {
+                const d = new Date(e.ts * 1000)
+                    .toISOString()
+                    .slice(0, 16)
+                    .replace('T', ' ');
+                lines.push(`- [${d}] ${e.note}`);
+            }
+        }
+        else {
+            lines.push('', '(no entries yet)');
+        }
+        await sendText(ctx.sock, ctx.jid, lines.join('\n'), ctx.quoted);
+        return;
+    }
+    if (sub === 'entries') {
+        const [slugRaw, nRaw] = args.split(/\s+/);
+        const slug = (slugRaw ?? '').toLowerCase();
+        const n = Math.max(1, Math.min(50, Number(nRaw) || 10));
+        if (!getJournal(slug)) {
+            await sendText(ctx.sock, ctx.jid, `No journal "${slug}".`, ctx.quoted);
+            return;
+        }
+        const entries = readEntries(slug, n);
+        if (!entries.length) {
+            await sendText(ctx.sock, ctx.jid, `No entries in "${slug}" yet.`, ctx.quoted);
+            return;
+        }
+        const lines = [`Last ${entries.length} entries in "${slug}":`];
+        for (const e of entries) {
+            const d = new Date(e.ts * 1000)
+                .toISOString()
+                .slice(0, 16)
+                .replace('T', ' ');
+            lines.push(`- [${d}] (${e.source}) ${e.note}`);
+        }
+        await sendText(ctx.sock, ctx.jid, lines.join('\n'), ctx.quoted);
+        return;
+    }
+    if (sub === 'pause' || sub === 'resume' || sub === 'archive' || sub === 'activate') {
+        const slug = args.split(/\s+/)[0]?.toLowerCase() ?? '';
+        if (!getJournal(slug)) {
+            await sendText(ctx.sock, ctx.jid, `No journal "${slug}".`, ctx.quoted);
+            return;
+        }
+        const status = sub === 'pause'
+            ? 'paused'
+            : sub === 'archive'
+                ? 'archived'
+                : 'active';
+        const updated = updateJournalStatus(slug, status);
+        await sendText(ctx.sock, ctx.jid, `Journal "${slug}" is now ${updated?.status}.`, ctx.quoted);
+        return;
+    }
+    await sendText(ctx.sock, ctx.jid, [
+        'Journal commands:',
+        '/journal list',
+        '/journal create <slug> <purpose>',
+        '/journal show <slug>',
+        '/journal entries <slug> [n]',
+        '/journal pause|resume|archive <slug>',
+    ].join('\n'), ctx.quoted);
+}
+function titleCase(slug) {
+    return slug
+        .split('-')
+        .map((p) => (p ? p[0].toUpperCase() + p.slice(1) : p))
+        .join(' ');
+}

package/dist/gateway/outgoing.js

@@ -107,6 +107,45 @@ export async function handleReply(job, result, originalMsg) {
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+// Proactive outbound: send a message to a chat without an incoming trigger.
+// Chunks, persists to the message log, never throws. Callers are responsible
+// for the canSendProactive() gate — this function does not re-check it.
+export async function initiate(params) {
+    const sock = getSocket();
+    if (!sock) {
+        logger.warn({ jid: params.jid }, 'initiate: no socket available');
+        return false;
+    }
+    const raw = params.text.replaceAll('—', ', ').replaceAll('–', '-');
+    if (!raw.trim())
+        return false;
+    try {
+        const chunks = chunkText(raw, config.reply.chunkChars);
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            await sendText(sock, params.jid, chunk);
+            await append({
+                id: `initiate-${Date.now()}-${i}`,
+                jid: params.jid,
+                direction: 'out',
+                fromMe: true,
+                sender: sock.user?.id ?? '',
+                senderNumber: config.owner.number,
+                timestamp: Math.floor(Date.now() / 1000),
+                text: chunk,
+                messageType: 'conversation',
+            });
+            if (i < chunks.length - 1)
+                await sleep(config.reply.chunkDelayMs);
+        }
+        logger.info({ jid: params.jid, chars: raw.length }, 'proactive message sent');
+        return true;
+    }
+    catch (err) {
+        logger.error({ err, jid: params.jid }, 'initiate failed');
+        return false;
+    }
+}
 export function chunkText(text, maxChars) {
     if (text.length <= maxChars)
         return [text];

package/dist/memory/digest-flag.js

@@ -1,8 +1,79 @@
-const DIGEST_RE = /\[DIGEST:\s*([^\]]+)\]\s*$/i;
+const TRAILING_TAG_RE = /\[(DIGEST|JOURNAL|JOURNAL-NEW|JOURNAL-PAUSE|JOURNAL-RESUME|JOURNAL-ARCHIVE):\s*([^\]]+)\]\s*$/i;
+// Peel trailing tags off the end of a reply. Supported:
+//   [DIGEST: <reason>]
+//   [JOURNAL:<slug> — <note>]         (append entry)
+//   [JOURNAL-NEW:<slug> — <purpose>]  (create journal)
+//   [JOURNAL-PAUSE:<slug>]
+//   [JOURNAL-RESUME:<slug>]
+//   [JOURNAL-ARCHIVE:<slug>]
+// Multiple tags are supported and can appear in any order at the tail.
+// Tags must be the LAST thing in the reply (after trimming trailing whitespace).
+export function extractFlags(reply) {
+    let current = reply;
+    let digest = null;
+    const journals = [];
+    const lifecycleOps = [];
+    while (true) {
+        const trimmed = current.replace(/\s+$/, '');
+        const match = trimmed.match(TRAILING_TAG_RE);
+        if (!match)
+            break;
+        const kind = match[1].toUpperCase();
+        const payload = (match[2] ?? '').trim();
+        if (kind === 'DIGEST') {
+            if (digest === null)
+                digest = payload;
+        }
+        else if (kind === 'JOURNAL') {
+            const parsed = parseJournalPayload(payload);
+            if (parsed)
+                journals.unshift(parsed);
+        }
+        else if (kind === 'JOURNAL-NEW') {
+            const parsed = parseJournalPayload(payload);
+            if (parsed) {
+                lifecycleOps.unshift({
+                    kind: 'new',
+                    slug: parsed.slug,
+                    purpose: parsed.note,
+                });
+            }
+        }
+        else if (kind === 'JOURNAL-PAUSE' ||
+            kind === 'JOURNAL-RESUME' ||
+            kind === 'JOURNAL-ARCHIVE') {
+            const slug = payload.trim().toLowerCase();
+            if (/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+                const op = kind === 'JOURNAL-PAUSE'
+                    ? 'pause'
+                    : kind === 'JOURNAL-RESUME'
+                        ? 'resume'
+                        : 'archive';
+                lifecycleOps.unshift({ kind: op, slug });
+            }
+        }
+        current = trimmed.slice(0, match.index).trimEnd();
+    }
+    return { clean: current, digest, journals, lifecycleOps };
+}
+// Legacy helper kept so existing callers still compile.
 export function extractDigestFlag(reply) {
-    const match = reply.match(DIGEST_RE);
+    const r = extractFlags(reply);
+    return { clean: r.clean, flag: r.digest };
+}
+const JOURNAL_SEP_RE = /\s*(?:[—\-–]|:)\s*/;
+function parseJournalPayload(payload) {
+    // Split on first em-dash, en-dash, hyphen, or colon between slug and note.
+    const match = payload.match(/^([a-zA-Z0-9][a-zA-Z0-9-]*)(.*)$/);
     if (!match)
-        return { clean: reply, flag: null };
-    const clean = reply.slice(0, match.index).trimEnd();
-    return { clean, flag: match[1]?.trim() ?? '' };
+        return null;
+    const slug = match[1].toLowerCase();
+    const rest = match[2] ?? '';
+    const sepMatch = rest.match(JOURNAL_SEP_RE);
+    if (!sepMatch || sepMatch.index !== 0)
+        return null;
+    const note = rest.slice(sepMatch[0].length).trim();
+    if (!note)
+        return null;
+    return { slug, note };
 }

package/dist/memory/journal-cadence.js

@@ -0,0 +1,120 @@
+// Cadence parsing and "is due?" evaluation for journals.
+//
+// Supported shapes:
+//   "daily HH:MM"        — daily at HH:MM in owner.timezone (e.g. "daily 21:00")
+//   "Xh"                 — every X hours (e.g. "24h")
+//   "Xd"                 — every X days (e.g. "3d")
+//   "Xm"                 — every X minutes (only for testing; rounded up)
+//
+// Quiet hours shape: "HH:MM-HH:MM" (may span midnight: "22:00-08:00")
+export function parseCadence(raw) {
+    if (!raw)
+        return null;
+    const s = raw.trim().toLowerCase();
+    const daily = s.match(/^daily\s+(\d{1,2}):(\d{2})$/);
+    if (daily) {
+        const hour = Number(daily[1]);
+        const minute = Number(daily[2]);
+        if (hour < 0 || hour > 23 || minute < 0 || minute > 59)
+            return null;
+        return { kind: 'daily', hour, minute };
+    }
+    const iv = s.match(/^(\d+)\s*([mhd])$/);
+    if (iv) {
+        const n = Number(iv[1]);
+        const unit = iv[2];
+        if (!Number.isFinite(n) || n <= 0)
+            return null;
+        const secs = unit === 'm' ? n * 60 : unit === 'h' ? n * 3600 : n * 86400;
+        return { kind: 'interval', seconds: secs };
+    }
+    return null;
+}
+// Returns unix seconds (ts) of the next scheduled firing AFTER the given
+// "lastFiredTs" (or since "now" if never fired). For daily cadences, the time
+// is computed in the owner's timezone.
+export function nextFireTs(params) {
+    const { cadence, lastFiredTs, now, timezone } = params;
+    if (cadence.kind === 'interval') {
+        const base = lastFiredTs ?? now;
+        return base + cadence.seconds;
+    }
+    // daily HH:MM in timezone
+    const anchor = lastFiredTs ?? now;
+    // Start from the day of anchor, then walk forward until target time > anchor.
+    let target = dailyTargetTs(anchor, cadence, timezone);
+    while (target <= anchor) {
+        target = dailyTargetTs(target + 1, cadence, timezone);
+    }
+    return target;
+}
+// For a given reference ts, compute the unix ts for HH:MM that same day in the
+// given timezone. May be earlier than ref if the clock time is past HH:MM.
+function dailyTargetTs(refTs, cadence, timezone) {
+    const parts = timezoneParts(refTs, timezone);
+    // Construct an ISO-like string for "that date at HH:MM in tz" and convert
+    // back to epoch via UTC offset derived from parts.
+    const y = parts.year;
+    const mo = parts.month;
+    const d = parts.day;
+    const ts = zonedDateTimeToEpoch(y, mo, d, cadence.hour, cadence.minute, timezone);
+    return ts;
+}
+export function timezoneParts(tsSeconds, timezone) {
+    const fmt = new Intl.DateTimeFormat('en-GB', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    });
+    const p = Object.fromEntries(fmt.formatToParts(new Date(tsSeconds * 1000)).map((x) => [x.type, x.value]));
+    return {
+        year: Number(p.year),
+        month: Number(p.month),
+        day: Number(p.day),
+        hour: Number(p.hour) % 24,
+        minute: Number(p.minute),
+        second: Number(p.second),
+    };
+}
+// Convert a local (zoned) date-time to epoch seconds. Uses Intl to derive the
+// UTC offset for that zone at that wall time.
+function zonedDateTimeToEpoch(year, month, day, hour, minute, timezone) {
+    // Start with the wall time treated as UTC, then correct by the tz offset.
+    const asUtcMs = Date.UTC(year, month - 1, day, hour, minute, 0);
+    // Get what that UTC moment looks like in the target timezone
+    const parts = timezoneParts(Math.floor(asUtcMs / 1000), timezone);
+    // Compute the diff between the wall time we wanted and what we got
+    const wantedMs = asUtcMs;
+    const gotMs = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, 0);
+    const offsetMs = gotMs - wantedMs;
+    return Math.floor((asUtcMs - offsetMs) / 1000);
+}
+// Quiet hours: is the given time inside the quiet-hours window (in tz)?
+// Accepts "HH:MM-HH:MM" (e.g. "22:00-08:00" = 10pm to 8am next day).
+export function isInQuietHours(params) {
+    const { now, window, timezone } = params;
+    if (!window)
+        return false;
+    const m = window.match(/^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/);
+    if (!m)
+        return false;
+    const startH = Number(m[1]);
+    const startM = Number(m[2]);
+    const endH = Number(m[3]);
+    const endM = Number(m[4]);
+    const parts = timezoneParts(now, timezone);
+    const curMin = parts.hour * 60 + parts.minute;
+    const startMin = startH * 60 + startM;
+    const endMin = endH * 60 + endM;
+    if (startMin <= endMin) {
+        // Non-wrapping window: [start, end)
+        return curMin >= startMin && curMin < endMin;
+    }
+    // Wrapping window: [start, 24:00) ∪ [00:00, end)
+    return curMin >= startMin || curMin < endMin;
+}