@mono-agent/agent-app 0.2.1 → 0.3.0

package/dist/launchd.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Thin, side-effect-light helpers around macOS launchd. The `launchctl` runner
+ * is injectable so orchestration can be unit tested without touching the real
+ * service domain. Everything here is pure except `makeLaunchctlRunner`.
+ */
+export interface LaunchctlResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type LaunchctlRunner = (args: readonly string[]) => Promise<LaunchctlResult>;
+export interface LaunchdPaths {
+    readonly plistPath: string;
+    readonly stdoutPath: string;
+    readonly stderrPath: string;
+    readonly logDir: string;
+    readonly launchAgentsDir: string;
+}
+export interface PlistInput {
+    readonly label: string;
+    readonly nodePath: string;
+    readonly cliPath: string;
+    readonly configPath: string;
+    readonly cwd: string;
+    readonly envFile?: string;
+    readonly port?: number;
+    readonly noConsole: boolean;
+    readonly stdoutPath: string;
+    readonly stderrPath: string;
+    readonly pathEnv: string;
+}
+/**
+ * A stable, launchd-legal label derived from the resolved config path. The
+ * folder name keeps it human-readable; an 8-char hash of the absolute config
+ * path disambiguates same-named folders and keeps the label deterministic so
+ * `start`/`stop`/`status` all address the same service.
+ */
+export declare function deriveLaunchdLabel(configPath: string): string;
+export declare function launchdPathsFor(label: string, home?: string): LaunchdPaths;
+export declare function escapeXml(value: string): string;
+/**
+ * The plist runs `node <cli.js> start --foreground …` (the existing blocking
+ * worker) in the config's directory. No secrets are written here — the worker
+ * loads `.env` from its working directory exactly like the foreground CLI.
+ */
+export declare function buildPlistXml(input: PlistInput): string;
+/**
+ * PATH for the background worker: the launching shell's PATH (so the user's
+ * toolchain is reachable) plus Homebrew/usr-local in case launchd started from
+ * a bare login. Never includes anything secret.
+ */
+export declare function defaultPathEnv(env?: Record<string, string | undefined>): string;
+export declare function domainTarget(uid: number): string;
+export declare function serviceTarget(label: string, uid: number): string;
+export declare function makeLaunchctlRunner(): LaunchctlRunner;
+/** True when the service is bootstrapped in the user's gui domain. */
+export declare function isLoaded(runner: LaunchctlRunner, label: string, uid: number): Promise<boolean>;
+/** Bootstrap (load + RunAtLoad-launch) the plist. Caller tolerates "already bootstrapped". */
+export declare function bootstrap(runner: LaunchctlRunner, plistPath: string, uid: number): Promise<LaunchctlResult>;
+/** Kill and restart an already-loaded service, picking up a rewritten plist. */
+export declare function kickstartRestart(runner: LaunchctlRunner, label: string, uid: number): Promise<LaunchctlResult>;
+/**
+ * Remove the service from the domain. Sends SIGTERM and — unlike a plain kill —
+ * prevents KeepAlive from relaunching it. Caller tolerates "not loaded".
+ */
+export declare function bootout(runner: LaunchctlRunner, label: string, uid: number): Promise<LaunchctlResult>;
+//# sourceMappingURL=launchd.d.ts.map

package/dist/launchd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launchd.d.ts","sourceRoot":"","sources":["../src/launchd.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAEpF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAOD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,YAAY,CAUrF;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAiDvD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAY5F;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,mBAAmB,IAAI,eAAe,CAmBrD;AAED,sEAAsE;AACtE,wBAAsB,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGpG;AAED,8FAA8F;AAC9F,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAEjH;AAED,gFAAgF;AAChF,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAEpH;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAE3G"}

package/dist/launchd.js

@@ -0,0 +1,164 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+import process from "node:process";
+const LABEL_PREFIX = "com.mono-agent";
+const MAX_FOLDER_SEGMENT = 40;
+const FALLBACK_PATH = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin";
+const PATH_EXTRAS = ["/opt/homebrew/bin", "/usr/local/bin"];
+/**
+ * A stable, launchd-legal label derived from the resolved config path. The
+ * folder name keeps it human-readable; an 8-char hash of the absolute config
+ * path disambiguates same-named folders and keeps the label deterministic so
+ * `start`/`stop`/`status` all address the same service.
+ */
+export function deriveLaunchdLabel(configPath) {
+    const resolved = resolve(configPath);
+    const folder = basename(dirname(resolved))
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/gu, "-")
+        .replace(/-+/gu, "-")
+        .replace(/^-+|-+$/gu, "")
+        .slice(0, MAX_FOLDER_SEGMENT)
+        .replace(/-+$/gu, "");
+    const hash = createHash("sha256").update(resolved).digest("hex").slice(0, 8);
+    return `${LABEL_PREFIX}.${folder.length === 0 ? "agent" : folder}-${hash}`;
+}
+export function launchdPathsFor(label, home = homedir()) {
+    const launchAgentsDir = resolve(home, "Library", "LaunchAgents");
+    const logDir = resolve(home, ".mono-agent", "logs");
+    return {
+        launchAgentsDir,
+        logDir,
+        plistPath: resolve(launchAgentsDir, `${label}.plist`),
+        stdoutPath: resolve(logDir, `${label}.out.log`),
+        stderrPath: resolve(logDir, `${label}.err.log`),
+    };
+}
+export function escapeXml(value) {
+    return value
+        .replace(/&/gu, "&")
+        .replace(/</gu, "&lt;")
+        .replace(/>/gu, "&gt;")
+        .replace(/"/gu, "&quot;")
+        .replace(/'/gu, "&apos;");
+}
+/**
+ * The plist runs `node <cli.js> start --foreground …` (the existing blocking
+ * worker) in the config's directory. No secrets are written here — the worker
+ * loads `.env` from its working directory exactly like the foreground CLI.
+ */
+export function buildPlistXml(input) {
+    const programArguments = [
+        input.nodePath,
+        input.cliPath,
+        "start",
+        "--foreground",
+        "--config",
+        input.configPath,
+        ...(input.envFile === undefined ? [] : ["--env-file", input.envFile]),
+        ...(input.port === undefined ? [] : ["--port", String(input.port)]),
+        ...(input.noConsole ? ["--no-console"] : []),
+    ];
+    const argsXml = programArguments.map((arg) => `    <string>${escapeXml(arg)}</string>`).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(input.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argsXml}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(input.cwd)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${escapeXml(input.pathEnv)}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(input.stdoutPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(input.stderrPath)}</string>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+</dict>
+</plist>
+`;
+}
+/**
+ * PATH for the background worker: the launching shell's PATH (so the user's
+ * toolchain is reachable) plus Homebrew/usr-local in case launchd started from
+ * a bare login. Never includes anything secret.
+ */
+export function defaultPathEnv(env = process.env) {
+    const current = env.PATH?.trim();
+    if (current === undefined || current.length === 0) {
+        return FALLBACK_PATH;
+    }
+    const parts = current.split(":").filter((part) => part.length > 0);
+    for (const extra of PATH_EXTRAS) {
+        if (!parts.includes(extra)) {
+            parts.push(extra);
+        }
+    }
+    return parts.join(":");
+}
+export function domainTarget(uid) {
+    return `gui/${uid}`;
+}
+export function serviceTarget(label, uid) {
+    return `gui/${uid}/${label}`;
+}
+export function makeLaunchctlRunner() {
+    return (args) => new Promise((resolvePromise) => {
+        const child = spawn("launchctl", [...args], { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            resolvePromise({ code: 127, stdout, stderr: `${stderr}${error.message}` });
+        });
+        child.on("close", (code) => {
+            resolvePromise({ code: code ?? 0, stdout, stderr });
+        });
+    });
+}
+/** True when the service is bootstrapped in the user's gui domain. */
+export async function isLoaded(runner, label, uid) {
+    const result = await runner(["print", serviceTarget(label, uid)]);
+    return result.code === 0;
+}
+/** Bootstrap (load + RunAtLoad-launch) the plist. Caller tolerates "already bootstrapped". */
+export async function bootstrap(runner, plistPath, uid) {
+    return await runner(["bootstrap", domainTarget(uid), plistPath]);
+}
+/** Kill and restart an already-loaded service, picking up a rewritten plist. */
+export async function kickstartRestart(runner, label, uid) {
+    return await runner(["kickstart", "-k", serviceTarget(label, uid)]);
+}
+/**
+ * Remove the service from the domain. Sends SIGTERM and — unlike a plain kill —
+ * prevents KeepAlive from relaunching it. Caller tolerates "not loaded".
+ */
+export async function bootout(runner, label, uid) {
+    return await runner(["bootout", serviceTarget(label, uid)]);
+}
+//# sourceMappingURL=launchd.js.map

package/dist/launchd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launchd.js","sourceRoot":"","sources":["../src/launchd.ts"],"names":[],"mappings":"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"}

package/dist/memory-rituals.d.ts

@@ -0,0 +1,51 @@
+/**
+ * In-app memory ritual scheduler for the `bujo` tier.
+ *
+ * Schedules `store.reflect()` and `store.migrate()` on their configured cron
+ * cadences (defaults: `0 3 * * *` / `0 4 1 * *`). Uses a hand-rolled minimal
+ * cron next-run calculator (5-field `m h dom mon dow`); avoids adding
+ * `cron-parser` as a direct dep of this package.
+ *
+ * Design guarantees:
+ * - Only schedules for `store.tier() === "bujo"` (needs the LLM tier).
+ * - Rituals default-enabled; set `enabled: false` to opt out.
+ * - Skip-overlap: never starts a run while the previous is in flight.
+ * - Never-throws: errors are caught and logged via `logger.warn`; the
+ *   scheduler reschedules after every run (success or failure).
+ * - Injectable `now` / `setTimer` / `clearTimer` for deterministic testing.
+ */
+export interface MemoryRitualSchedule {
+    readonly enabled?: boolean;
+    readonly cron?: string;
+}
+export interface StartMemoryRitualsInput {
+    readonly store: {
+        tier(): string;
+        reflect(): Promise<unknown>;
+        migrate(): Promise<unknown>;
+    };
+    /** From config.memory.reflection */
+    readonly reflection?: MemoryRitualSchedule;
+    /** From config.memory.migration */
+    readonly migration?: MemoryRitualSchedule;
+    readonly logger?: {
+        info(m: string): void;
+        warn(m: string): void;
+    };
+    /** Injectable clock for tests. Defaults to `() => new Date()`. */
+    readonly now?: () => Date;
+    /**
+     * Injectable timer factory for tests.
+     * Defaults to a `setTimeout` wrapper returning the timeout handle.
+     */
+    readonly setTimer?: (cb: () => void, ms: number) => {
+        unref?: () => void;
+    };
+    /** Injectable timer canceller. Defaults to `clearTimeout`. */
+    readonly clearTimer?: (handle: unknown) => void;
+}
+export interface RunningRituals {
+    stop(): void;
+}
+export declare function startMemoryRituals(input: StartMemoryRitualsInput): RunningRituals;
+//# sourceMappingURL=memory-rituals.d.ts.map

package/dist/memory-rituals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-rituals.d.ts","sourceRoot":"","sources":["../src/memory-rituals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,IAAI,IAAI,MAAM,CAAC;QACf,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;QAC5B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;KAC7B,CAAC;IACF,oCAAoC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAC3C,mCAAmC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;IACF,kEAAkE;IAClE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK;QAAE,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IAC3E,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,IAAI,IAAI,CAAC;CACd;AAMD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,cAAc,CAqGjF"}

package/dist/memory-rituals.js

@@ -0,0 +1,228 @@
+/**
+ * In-app memory ritual scheduler for the `bujo` tier.
+ *
+ * Schedules `store.reflect()` and `store.migrate()` on their configured cron
+ * cadences (defaults: `0 3 * * *` / `0 4 1 * *`). Uses a hand-rolled minimal
+ * cron next-run calculator (5-field `m h dom mon dow`); avoids adding
+ * `cron-parser` as a direct dep of this package.
+ *
+ * Design guarantees:
+ * - Only schedules for `store.tier() === "bujo"` (needs the LLM tier).
+ * - Rituals default-enabled; set `enabled: false` to opt out.
+ * - Skip-overlap: never starts a run while the previous is in flight.
+ * - Never-throws: errors are caught and logged via `logger.warn`; the
+ *   scheduler reschedules after every run (success or failure).
+ * - Injectable `now` / `setTimer` / `clearTimer` for deterministic testing.
+ */
+const DEFAULT_REFLECTION_CRON = "0 3 * * *";
+const DEFAULT_MIGRATION_CRON = "0 4 1 * *";
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+export function startMemoryRituals(input) {
+    const { store, logger } = input;
+    // Only schedule for the bujo tier.
+    if (store.tier() !== "bujo") {
+        return noopRituals();
+    }
+    const now = input.now ?? (() => new Date());
+    const setTimer = input.setTimer ?? defaultSetTimer;
+    const clearTimer = input.clearTimer ?? ((h) => clearTimeout(h));
+    const handles = [];
+    let stopped = false;
+    function scheduleRitual(name, cronExpr, run) {
+        let inFlight = false;
+        let currentHandle;
+        function schedule() {
+            if (stopped) {
+                return;
+            }
+            const current = now();
+            let delayMs;
+            try {
+                delayMs = nextCronDelayMs(cronExpr, current);
+            }
+            catch (err) {
+                logger?.warn(`Memory ritual "${name}" has an invalid cron expression "${cronExpr}": ${err instanceof Error ? err.message : String(err)}. Ritual disabled.`);
+                return;
+            }
+            const handle = setTimer(() => {
+                // Remove from tracked handles (it has fired)
+                const idx = handles.indexOf(handle);
+                if (idx !== -1) {
+                    handles.splice(idx, 1);
+                }
+                currentHandle = undefined;
+                if (stopped) {
+                    return;
+                }
+                if (inFlight) {
+                    // Skip: the previous run is still in flight. Do NOT reschedule here — the in-flight run's
+                    // .finally schedules the next tick, keeping exactly one pending timer per ritual (no double-schedule).
+                    logger?.warn(`Memory ritual "${name}" skipped — previous run is still in flight.`);
+                    return;
+                }
+                inFlight = true;
+                run()
+                    .catch((err) => {
+                    logger?.warn(`Memory ritual "${name}" failed: ${err instanceof Error ? err.message : String(err)}.`);
+                })
+                    .finally(() => {
+                    inFlight = false;
+                    schedule();
+                });
+            }, delayMs);
+            handle.unref?.();
+            currentHandle = handle;
+            handles.push(handle);
+        }
+        schedule();
+        void currentHandle; // suppress unused-variable lint; reference is in handles
+    }
+    // Schedule reflection ritual
+    if (input.reflection?.enabled !== false) {
+        const cronExpr = input.reflection?.cron ?? DEFAULT_REFLECTION_CRON;
+        scheduleRitual("reflect", cronExpr, () => store.reflect());
+    }
+    // Schedule migration ritual
+    if (input.migration?.enabled !== false) {
+        const cronExpr = input.migration?.cron ?? DEFAULT_MIGRATION_CRON;
+        scheduleRitual("migrate", cronExpr, () => store.migrate());
+    }
+    return {
+        stop() {
+            stopped = true;
+            for (const h of handles.splice(0)) {
+                if (h !== undefined) {
+                    clearTimer(h);
+                }
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Minimal 5-field cron next-run calculator
+// ---------------------------------------------------------------------------
+//
+// Supports `m h dom mon dow` where each field is:
+//   *              matches every value
+//   <number>       exact match
+//   */n            step (e.g. */5 = every 5)
+//   a-b            range
+//   a,b,c          list
+//   a-b/n          range with step
+//
+// Sufficient for the two defaults + most simple expressions.
+// Time complexity: O(minutes-until-next-run), bounded by 366*24*60 ≈ 530k.
+// ---------------------------------------------------------------------------
+function nextCronDelayMs(expression, from) {
+    const fields = expression.trim().split(/\s+/u);
+    if (fields.length !== 5) {
+        throw new Error(`Expected 5 fields; got ${fields.length}`);
+    }
+    const [mField, hField, domField, monField, dowField] = fields;
+    // Search forward minute by minute for up to ~2 years
+    // Start from the NEXT minute after `from` (cron fires at the start of the minute)
+    const candidate = new Date(from.getTime());
+    // Advance to the next whole minute
+    candidate.setUTCSeconds(0, 0);
+    candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+    const MAX_ITERATIONS = 365 * 24 * 60 * 2; // 2 years in minutes
+    for (let i = 0; i < MAX_ITERATIONS; i++) {
+        const min = candidate.getUTCMinutes();
+        const hour = candidate.getUTCHours();
+        const dom = candidate.getUTCDate();
+        const mon = candidate.getUTCMonth() + 1; // 1-12
+        const dow = candidate.getUTCDay(); // 0 (Sun) – 6 (Sat)
+        if (matchField(mField, min, 0, 59) &&
+            matchField(hField, hour, 0, 23) &&
+            matchField(monField, mon, 1, 12) &&
+            matchDayField(domField, dowField, dom, dow)) {
+            return candidate.getTime() - from.getTime();
+        }
+        candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+    }
+    throw new Error(`No match found in 2 years for cron expression "${expression}"`);
+}
+/**
+ * Standard cron DOM/DOW logic:
+ * - If BOTH dom and dow are restricted (not `*`), either matching satisfies.
+ * - If only one is restricted, only that one must match.
+ * - If both are `*`, always matches.
+ */
+function matchDayField(domField, dowField, dom, dow) {
+    const domRestricted = domField !== "*";
+    const dowRestricted = dowField !== "*";
+    if (domRestricted && dowRestricted) {
+        return matchField(domField, dom, 1, 31) || matchField(dowField, dow, 0, 6);
+    }
+    if (domRestricted) {
+        return matchField(domField, dom, 1, 31);
+    }
+    if (dowRestricted) {
+        return matchField(dowField, dow, 0, 6);
+    }
+    return true;
+}
+function matchField(field, value, _min, _max) {
+    // Comma-separated list
+    const parts = field.split(",");
+    return parts.some((part) => matchPart(part.trim(), value, _min, _max));
+}
+function matchPart(part, value, min, max) {
+    // Wildcard
+    if (part === "*") {
+        return true;
+    }
+    // Step: */n or a-b/n
+    const slashIdx = part.indexOf("/");
+    if (slashIdx !== -1) {
+        const stepStr = part.slice(slashIdx + 1);
+        const step = parseInt(stepStr, 10);
+        if (Number.isNaN(step) || step <= 0) {
+            throw new Error(`Invalid step in cron field part "${part}"`);
+        }
+        const rangePart = part.slice(0, slashIdx);
+        let rangeStart = min;
+        let rangeEnd = max;
+        if (rangePart !== "*") {
+            const dashIdx = rangePart.indexOf("-");
+            if (dashIdx !== -1) {
+                rangeStart = parseInt(rangePart.slice(0, dashIdx), 10);
+                rangeEnd = parseInt(rangePart.slice(dashIdx + 1), 10);
+            }
+            else {
+                rangeStart = parseInt(rangePart, 10);
+                rangeEnd = max;
+            }
+        }
+        if (value < rangeStart || value > rangeEnd) {
+            return false;
+        }
+        return (value - rangeStart) % step === 0;
+    }
+    // Range: a-b
+    const dashIdx = part.indexOf("-");
+    if (dashIdx !== -1) {
+        const rangeStart = parseInt(part.slice(0, dashIdx), 10);
+        const rangeEnd = parseInt(part.slice(dashIdx + 1), 10);
+        return value >= rangeStart && value <= rangeEnd;
+    }
+    // Exact number
+    const num = parseInt(part, 10);
+    if (Number.isNaN(num)) {
+        throw new Error(`Invalid cron field part "${part}"`);
+    }
+    return value === num;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function noopRituals() {
+    return { stop() { } };
+}
+function defaultSetTimer(cb, ms) {
+    const handle = setTimeout(cb, ms);
+    return { unref: () => handle.unref() };
+}
+//# sourceMappingURL=memory-rituals.js.map

package/dist/memory-rituals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-rituals.js","sourceRoot":"","sources":["../src/memory-rituals.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-app",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Config-first mono-agent host: builds a responder and starts every configured communication channel, operator console, and traceability from one mono-agent.config.json.",
   "type": "module",
   "license": "UNLICENSED",
@@ -22,20 +22,20 @@
     "README.md"
   ],
   "dependencies": {
-    "@mono-agent/a2a-adapter": "0.2.1",
-    "@mono-agent/agent-contracts": "0.2.1",
-    "@mono-agent/agent-host": "0.2.1",
-    "@mono-agent/config": "0.2.1",
-    "@mono-agent/cron-adapter": "0.2.1",
-    "@mono-agent/observability": "0.2.1",
-    "@mono-agent/openai-api-adapter": "0.2.1",
-    "@mono-agent/operator-console": "0.2.1",
-    "@mono-agent/runtime-adapter": "0.2.1",
-    "@mono-agent/settings": "0.2.1",
-    "@mono-agent/slack-adapter": "0.2.1",
-    "@mono-agent/telegram-adapter": "0.2.1",
-    "@mono-agent/webhook-adapter": "0.2.1",
-    "@mono-agent/whatsapp-adapter": "0.2.1"
+    "@mono-agent/a2a-adapter": "0.3.0",
+    "@mono-agent/agent-contracts": "0.3.0",
+    "@mono-agent/agent-host": "0.3.0",
+    "@mono-agent/config": "0.3.0",
+    "@mono-agent/cron-adapter": "0.3.0",
+    "@mono-agent/observability": "0.3.0",
+    "@mono-agent/openai-api-adapter": "0.3.0",
+    "@mono-agent/operator-console": "0.3.0",
+    "@mono-agent/runtime-adapter": "0.3.0",
+    "@mono-agent/settings": "0.3.0",
+    "@mono-agent/slack-adapter": "0.3.0",
+    "@mono-agent/telegram-adapter": "0.3.0",
+    "@mono-agent/webhook-adapter": "0.3.0",
+    "@mono-agent/whatsapp-adapter": "0.3.0"
   },
   "publishConfig": {
     "access": "public"

package/skills/mono-agent-composer/SKILL.md

@@ -41,7 +41,7 @@ Everything below runs in the user's agent folder, not the workspace.
 2. **Scaffold.** In the user's folder run:
 
    ```bash
-   mono-agent init --model <ref> [--fallback-models <csv>] [--memory markdown|journal]
+   mono-agent init --model <ref> [--fallback-models <csv>] [--memory lite|journal|bujo]
    ```
 
    This writes a minimal `mono-agent.config.json` (webhook enabled as the zero-credential smoke channel), an `IDENTITY.md` that references any knowledge files already present, and `.mono-agent/` working directories. It never overwrites existing files.
@@ -63,7 +63,7 @@ Everything below runs in the user's agent folder, not the workspace.
 
 ## When Config Is Not Enough
 
-Config-first covers one responder served over any combination of the seven channels (webhook, OpenAI-compatible API, Telegram, Slack, WhatsApp, A2A, cron) plus the operator console, sandbox, memory (markdown or journal with entity graph and optional semantic search), and traceability. Drop to programmatic composition only for: custom runtimes (`MonoRuntimeLike`, incl. the OpenAI Agents SDK), request-scoped runtime extensions, tool approval gates, structured output schemas, multi-agent orchestration (`@mono-agent/agent-orchestrator`), custom channel message texts, or bespoke transports — `references/feature-coverage.md` lists which features are config keys and which are code-only. Read `references/package-map.md` for the package boundaries, and start from `startMonoAgentApp({ drivers, runtime, ... })` or `@mono-agent/agent-host` rather than re-writing lifecycle glue. For eval suites over the composed agent, use `@mono-agent/agent-evals`.
+Config-first covers one responder served over any combination of the seven channels (webhook, OpenAI-compatible API, Telegram, Slack, WhatsApp, A2A, cron) plus the operator console, sandbox, memory (lite with FTS-only recall, journal with hybrid BM25+vector recall + Ollama embeddings, or bujo with SQLite-indexed hybrid recall + LLM capture/reconcile + entity graph + auto-scheduled reflection/migration), and traceability. Drop to programmatic composition only for: custom runtimes (`MonoRuntimeLike`, incl. the OpenAI Agents SDK), request-scoped runtime extensions, tool approval gates, structured output schemas, multi-agent orchestration (`@mono-agent/agent-orchestrator`), custom channel message texts, or bespoke transports — `references/feature-coverage.md` lists which features are config keys and which are code-only. Read `references/package-map.md` for the package boundaries, and start from `startMonoAgentApp({ drivers, runtime, ... })` or `@mono-agent/agent-host` rather than re-writing lifecycle glue. For eval suites over the composed agent, use `@mono-agent/agent-evals`.
 
 ## Implementation References