@c4t4/heyamigo 0.1.18 → 0.3.0

package/dist/memory/journals.js

@@ -0,0 +1,314 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'fs';
+import { dirname, resolve } from 'path';
+import { logger } from '../logger.js';
+import { parseFrontmatter, serializeFrontmatter, } from './frontmatter.js';
+import { memoryRoot } from './paths.js';
+// ---------- paths ----------
+function journalsRoot() {
+    return resolve(memoryRoot(), 'journals');
+}
+function journalDir(slug) {
+    return resolve(journalsRoot(), slug);
+}
+function journalIndexPath(slug) {
+    return resolve(journalDir(slug), 'index.md');
+}
+function journalEntriesPath(slug) {
+    return resolve(journalDir(slug), 'entries.jsonl');
+}
+function journalsIndexPath() {
+    return resolve(journalsRoot(), 'index.md');
+}
+function journalObserverStatePath(slug) {
+    return resolve(journalDir(slug), 'observer-state.json');
+}
+function journalNudgeStatePath(slug) {
+    return resolve(journalDir(slug), 'nudge-state.json');
+}
+// ---------- low-level fs ----------
+function ensureDirFor(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+function readIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, 'utf-8');
+}
+// ---------- scaffold ----------
+export function ensureJournalsScaffold() {
+    mkdirSync(journalsRoot(), { recursive: true });
+    if (!existsSync(journalsIndexPath())) {
+        writeFileSync(journalsIndexPath(), '# journals\n\n(empty)\n', 'utf-8');
+    }
+}
+// ---------- slug rules ----------
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,47}$/;
+export function isValidSlug(slug) {
+    return SLUG_RE.test(slug);
+}
+// ---------- parse / serialize ----------
+function parseJournal(slug, raw) {
+    const { data, body } = parseFrontmatter(raw);
+    const name = typeof data.name === 'string' ? data.name : slug;
+    const purpose = typeof data.purpose === 'string' ? data.purpose : '';
+    const fields = Array.isArray(data.fields)
+        ? data.fields.map(String)
+        : [];
+    const status = data.status === 'paused' || data.status === 'archived'
+        ? data.status
+        : 'active';
+    const cadence = {
+        checkin: pickString(data.checkin),
+        followup_after: pickString(data.followup_after),
+        nudge_if_silent: pickString(data.nudge_if_silent),
+    };
+    const created_at = typeof data.created_at === 'string' ? data.created_at : '';
+    const updated_at = typeof data.updated_at === 'string' ? data.updated_at : created_at;
+    return {
+        slug,
+        name,
+        purpose,
+        fields,
+        cadence,
+        status,
+        quiet_hours: pickString(data.quiet_hours),
+        created_at,
+        updated_at,
+        body,
+    };
+}
+function pickString(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function journalToFrontmatter(j) {
+    const fm = {
+        slug: j.slug,
+        name: j.name,
+        purpose: j.purpose,
+        fields: j.fields,
+        status: j.status,
+        created_at: j.created_at,
+        updated_at: j.updated_at,
+    };
+    if (j.cadence.checkin)
+        fm.checkin = j.cadence.checkin;
+    if (j.cadence.followup_after)
+        fm.followup_after = j.cadence.followup_after;
+    if (j.cadence.nudge_if_silent)
+        fm.nudge_if_silent = j.cadence.nudge_if_silent;
+    if (j.quiet_hours)
+        fm.quiet_hours = j.quiet_hours;
+    return fm;
+}
+// ---------- CRUD ----------
+export function listJournals() {
+    const root = journalsRoot();
+    if (!existsSync(root))
+        return [];
+    const slugs = readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort();
+    const out = [];
+    for (const slug of slugs) {
+        const raw = readIfExists(journalIndexPath(slug));
+        if (!raw)
+            continue;
+        const j = parseJournal(slug, raw);
+        if (j)
+            out.push(j);
+    }
+    return out;
+}
+export function getJournal(slug) {
+    if (!isValidSlug(slug))
+        return null;
+    const raw = readIfExists(journalIndexPath(slug));
+    if (!raw)
+        return null;
+    return parseJournal(slug, raw);
+}
+export function journalExists(slug) {
+    return isValidSlug(slug) && existsSync(journalIndexPath(slug));
+}
+export function createJournal(input) {
+    if (!isValidSlug(input.slug)) {
+        throw new Error(`Invalid journal slug "${input.slug}". Use lowercase letters, digits, and hyphens (max 48 chars, must start with letter/digit).`);
+    }
+    if (journalExists(input.slug)) {
+        throw new Error(`Journal "${input.slug}" already exists.`);
+    }
+    const now = new Date().toISOString().slice(0, 10);
+    // Default cadence: nudge after 3 days of silence on this topic. No daily
+    // check-in by default — that would be too pushy for most journals. Owner
+    // can tune by editing the journal's index.md frontmatter directly.
+    const cadence = input.cadence ?? {
+        nudge_if_silent: '3d',
+    };
+    const journal = {
+        slug: input.slug,
+        name: input.name,
+        purpose: input.purpose,
+        fields: input.fields ?? [],
+        cadence,
+        status: 'active',
+        quiet_hours: input.quiet_hours,
+        created_at: now,
+        updated_at: now,
+        body: input.body ??
+            `# ${input.name}\n\n${input.purpose}\n\n## How this journal is used\n\nEntries are captured by the assistant when topics relevant to this journal come up. See entries.jsonl for the log.\n`,
+    };
+    writeJournal(journal);
+    refreshJournalsIndex();
+    logger.info({ slug: journal.slug }, 'journal created');
+    return journal;
+}
+export function writeJournal(j) {
+    const content = serializeFrontmatter(journalToFrontmatter(j), j.body);
+    const path = journalIndexPath(j.slug);
+    ensureDirFor(path);
+    writeFileSync(path, content, 'utf-8');
+}
+export function updateJournalStatus(slug, status) {
+    const j = getJournal(slug);
+    if (!j)
+        return null;
+    j.status = status;
+    j.updated_at = new Date().toISOString().slice(0, 10);
+    writeJournal(j);
+    refreshJournalsIndex();
+    return j;
+}
+// ---------- entries ----------
+export function appendEntry(slug, entry) {
+    if (!journalExists(slug)) {
+        logger.warn({ slug }, 'journal append ignored: unknown slug');
+        return false;
+    }
+    const full = {
+        ts: entry.ts ?? Math.floor(Date.now() / 1000),
+        source: entry.source,
+        jid: entry.jid,
+        senderNumber: entry.senderNumber,
+        note: entry.note,
+    };
+    const path = journalEntriesPath(slug);
+    ensureDirFor(path);
+    appendFileSync(path, JSON.stringify(full) + '\n', 'utf-8');
+    logger.info({ slug, source: full.source, jid: full.jid }, 'journal entry appended');
+    return true;
+}
+export function readEntries(slug, limit = 100) {
+    const raw = readIfExists(journalEntriesPath(slug));
+    if (!raw)
+        return [];
+    const lines = raw.trim().split(/\r?\n/).filter(Boolean);
+    const tail = limit > 0 ? lines.slice(-limit) : lines;
+    const out = [];
+    for (const line of tail) {
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return out;
+}
+// ---------- index ----------
+export function refreshJournalsIndex() {
+    const journals = listJournals();
+    const lines = ['# journals', ''];
+    if (journals.length === 0) {
+        lines.push('(empty)');
+    }
+    else {
+        for (const j of journals) {
+            lines.push(`- ${j.slug}/ [${j.status}] — ${j.purpose || j.name}`);
+        }
+    }
+    lines.push('');
+    const path = journalsIndexPath();
+    ensureDirFor(path);
+    writeFileSync(path, lines.join('\n'), 'utf-8');
+}
+// ---------- preamble helper ----------
+// Short one-liner per active journal for the [Journals: active] preamble block.
+// Only returns active journals (not paused/archived).
+export function buildJournalsPreambleBlock() {
+    const journals = listJournals().filter((j) => j.status === 'active');
+    if (journals.length === 0)
+        return null;
+    const lines = [];
+    for (const j of journals) {
+        const cadence = summarizeCadence(j.cadence);
+        const cadenceSuffix = cadence ? ` (${cadence})` : '';
+        lines.push(`- ${j.slug}: ${j.purpose || j.name}${cadenceSuffix}`);
+    }
+    return lines.join('\n');
+}
+function summarizeCadence(c) {
+    const bits = [];
+    if (c.checkin)
+        bits.push(`check-in ${c.checkin}`);
+    if (c.followup_after)
+        bits.push(`follow-up ${c.followup_after}`);
+    if (c.nudge_if_silent)
+        bits.push(`nudge if silent ${c.nudge_if_silent}`);
+    return bits.join('; ');
+}
+export function loadObserverState(slug) {
+    const raw = readIfExists(journalObserverStatePath(slug));
+    if (!raw)
+        return { jids: {} };
+    try {
+        const parsed = JSON.parse(raw);
+        return { jids: parsed.jids ?? {} };
+    }
+    catch {
+        return { jids: {} };
+    }
+}
+export function saveObserverState(slug, state) {
+    const path = journalObserverStatePath(slug);
+    ensureDirFor(path);
+    writeFileSync(path, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+export function getLastScannedTs(slug, jid) {
+    const state = loadObserverState(slug);
+    return state.jids[jid]?.lastScannedTs ?? 0;
+}
+export function setLastScannedTs(slug, jid, ts) {
+    const state = loadObserverState(slug);
+    state.jids[jid] = { lastScannedTs: ts };
+    saveObserverState(slug, state);
+}
+export function loadNudgeState(slug) {
+    const raw = readIfExists(journalNudgeStatePath(slug));
+    if (!raw)
+        return { lastCheckinTs: 0, lastSilentNudgeTs: 0, snoozedUntilTs: 0 };
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            lastCheckinTs: parsed.lastCheckinTs ?? 0,
+            lastSilentNudgeTs: parsed.lastSilentNudgeTs ?? 0,
+            snoozedUntilTs: parsed.snoozedUntilTs ?? 0,
+        };
+    }
+    catch {
+        return { lastCheckinTs: 0, lastSilentNudgeTs: 0, snoozedUntilTs: 0 };
+    }
+}
+export function saveNudgeState(slug, state) {
+    const path = journalNudgeStatePath(slug);
+    ensureDirFor(path);
+    writeFileSync(path, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+export function snoozeJournal(slug, untilTs) {
+    if (!journalExists(slug))
+        return false;
+    const state = loadNudgeState(slug);
+    state.snoozedUntilTs = untilTs;
+    saveNudgeState(slug, state);
+    return true;
+}

package/dist/memory/preamble.js

@@ -1,11 +1,13 @@
 import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
 import { config } from '../config.js';
+import { buildJournalsPreambleBlock, ensureJournalsScaffold, } from './journals.js';
 import { masterIndexPath, treeIndexPath } from './paths.js';
 import { routeIndexes } from './router.js';
 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.`;
 function buildCriticalSection(params) {
     const { senderNumber, roleName, role, userName } = params;
     const who = userName
@@ -34,6 +36,7 @@ function buildCriticalSection(params) {
 }
 export function buildMemoryPreamble(params) {
     ensureScaffold();
+    ensureJournalsScaffold();
     const { name: roleName, role, userName } = getRoleForContext(params.senderNumber, params.isGroup ?? params.jid.endsWith('@g.us'));
     const sections = [];
     // Identity — tell Claude its name
@@ -108,7 +111,15 @@ export function buildMemoryPreamble(params) {
     if (entityBlocks.length) {
         sections.push(`${label}\n${entityBlocks.join('\n\n')}`);
     }
-    sections.push(`[Instruction]\n${DIGEST_REMINDER}`);
+    // 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];
+    if (journalsBlock) {
+        sections.push(`[Journals: active]\n${journalsBlock}`);
+        instructions.push(JOURNAL_REMINDER);
+    }
+    sections.push(`[Instruction]\n${instructions.join('\n\n')}`);
     return sections.join('\n\n');
 }
 function readIfExists(path) {

package/dist/memory/scheduler.js

@@ -62,8 +62,20 @@ async function sweep() {
                 .catch((err) => logger.error({ err, jid }, 'sweep digest push failed'));
         }
     }
+    // Journal observer pass: scans recent messages per active journal for
+    // entries Claude missed (i.e. when the bot wasn't mentioned). Runs once
+    // per sweep cycle; each journal maintains its own last-scanned-ts.
+    try {
+        const { runJournalObserverSweep } = await import('./journal-observer.js');
+        await runJournalObserverSweep();
+    }
+    catch (err) {
+        logger.error({ err }, 'journal observer sweep failed');
+    }
 }
 let sweepTimer = null;
+let nudgeTimer = null;
+const NUDGE_TICK_MS = 5 * 60 * 1000; // 5 minutes
 export function startScheduler() {
     if (sweepTimer)
         return;
@@ -72,13 +84,36 @@ export function startScheduler() {
     sweepTimer = setInterval(() => {
         void sweep().catch((err) => logger.error({ err }, 'sweep failed'));
     }, config.memory.sweepIntervalMs);
-    logger.info({ intervalMs: config.memory.sweepIntervalMs }, 'memory scheduler started');
+    // Faster tick just for proactive journal nudges (check-ins, silent-nudges).
+    // The memory-sweep cycle (default 3h) is too coarse for a "daily 21:00"
+    // check-in. This tick is cheap: it only spawns Claude when something is
+    // actually due for a journal.
+    nudgeTimer = setInterval(() => {
+        void runNudgeTickSafe();
+    }, NUDGE_TICK_MS);
+    logger.info({
+        intervalMs: config.memory.sweepIntervalMs,
+        nudgeTickMs: NUDGE_TICK_MS,
+    }, 'memory scheduler started');
+}
+async function runNudgeTickSafe() {
+    try {
+        const { runNudgeTick } = await import('./journal-nudger.js');
+        await runNudgeTick();
+    }
+    catch (err) {
+        logger.error({ err }, 'nudge tick failed');
+    }
 }
 export function stopScheduler() {
     if (sweepTimer) {
         clearInterval(sweepTimer);
         sweepTimer = null;
     }
+    if (nudgeTimer) {
+        clearInterval(nudgeTimer);
+        nudgeTimer = null;
+    }
     for (const t of pendingTimers.values())
         clearTimeout(t);
     pendingTimers.clear();

package/dist/queue/worker.js

@@ -1,7 +1,8 @@
 import { askClaude } from '../ai/claude.js';
 import { clearSession, setSession, setUsage } from '../ai/sessions.js';
 import { logger } from '../logger.js';
-import { extractDigestFlag } from '../memory/digest-flag.js';
+import { extractFlags } from '../memory/digest-flag.js';
+import { appendEntry, createJournal, getJournal, isValidSlug, updateJournalStatus, } from '../memory/journals.js';
 import { scheduleDigest } from '../memory/scheduler.js';
 function isStaleSessionError(err) {
     return (err instanceof Error &&
@@ -25,17 +26,73 @@ async function callClaude(job) {
         totalContextTokens,
         updatedAt: Math.floor(Date.now() / 1000),
     });
-    const { clean, flag } = extractDigestFlag(reply);
-    if (flag) {
-        logger.info({ jid: job.jid, number: job.senderNumber, reason: flag }, 'DIGEST flag raised, scheduling');
+    const { clean, digest, journals, lifecycleOps } = extractFlags(reply);
+    if (digest) {
+        logger.info({ jid: job.jid, number: job.senderNumber, reason: digest }, 'DIGEST flag raised, scheduling');
         scheduleDigest({
             jid: job.jid,
             number: job.senderNumber,
-            reason: flag,
+            reason: digest,
         });
     }
+    // Lifecycle ops run BEFORE entry appends so that a reply creating a new
+    // journal AND flagging its first entry in the same turn works correctly.
+    for (const op of lifecycleOps) {
+        if (!isValidSlug(op.slug)) {
+            logger.warn({ op, jid: job.jid }, 'journal lifecycle op: invalid slug, dropped');
+            continue;
+        }
+        try {
+            if (op.kind === 'new') {
+                if (getJournal(op.slug)) {
+                    logger.info({ slug: op.slug }, 'JOURNAL-NEW for existing slug, ignored');
+                    continue;
+                }
+                createJournal({
+                    slug: op.slug,
+                    name: titleCase(op.slug),
+                    purpose: op.purpose,
+                });
+                logger.info({ slug: op.slug, jid: job.jid }, 'journal created via bot marker');
+            }
+            else {
+                const status = op.kind === 'pause'
+                    ? 'paused'
+                    : op.kind === 'archive'
+                        ? 'archived'
+                        : 'active';
+                const updated = updateJournalStatus(op.slug, status);
+                if (updated) {
+                    logger.info({ slug: op.slug, status, jid: job.jid }, 'journal status updated via bot marker');
+                }
+                else {
+                    logger.warn({ op, jid: job.jid }, 'journal lifecycle op: unknown slug, dropped');
+                }
+            }
+        }
+        catch (err) {
+            logger.error({ err, op, jid: job.jid }, 'journal lifecycle op failed');
+        }
+    }
+    for (const j of journals) {
+        const ok = appendEntry(j.slug, {
+            source: 'reactive',
+            jid: job.jid,
+            senderNumber: job.senderNumber,
+            note: j.note,
+        });
+        if (!ok) {
+            logger.warn({ slug: j.slug, jid: job.jid }, 'JOURNAL flag pointed at unknown slug, dropped');
+        }
+    }
     return { reply: clean };
 }
+function titleCase(slug) {
+    return slug
+        .split('-')
+        .map((p) => (p ? p[0].toUpperCase() + p.slice(1) : p))
+        .join(' ');
+}
 export async function processJob(job) {
     try {
         return await callClaude(job);

package/dist/wa/whitelist.js

@@ -96,9 +96,11 @@ function save(next) {
 export function getAccess() {
     return current;
 }
-// Guardrail for proactive (unsolicited) messaging. Returns true ONLY if the
-// target chat has an explicit proactive:true entry. Default is deny — no
-// journal/scheduler/observer may message a chat without explicit opt-in.
+// Guardrail for proactive (unsolicited) messaging. Default deny.
+//
+// Exception: the owner's own self-DM is always allowed — the owner implicitly
+// consents to the bot nudging them in their own DM. Other DMs and groups
+// require an explicit `proactive: true` entry in access.json.
 export function canSendProactive(jid) {
     const isGroup = jid.endsWith('@g.us');
     if (isGroup) {
@@ -108,6 +110,9 @@ export function canSendProactive(jid) {
     const number = jidDecode(jid)?.user;
     if (!number)
         return false;
+    // Owner's self-DM is always allowed.
+    if (config.owner.number && number === config.owner.number)
+        return true;
     const entry = current.dms.allowed.find((d) => d.number === number);
     return entry?.proactive === true;
 }

package/package.json

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