@tloncorp/openclaw 0.2.0 → 0.4.1

package/dist/src/nudge-decision.js

@@ -0,0 +1,309 @@
+/**
+ * Pure decisioning helpers for the re-engagement nudge scheduler.
+ *
+ * All functions here are deterministic and do not perform I/O. The
+ * scheduler uses them to compute whether a tick should send anything.
+ */
+export const DEFAULT_ACTIVE_HOURS_START = "09:00";
+export const DEFAULT_ACTIVE_HOURS_END = "21:00";
+export const DEFAULT_ACTIVE_HOURS_TIMEZONE = "America/New_York";
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+/** Whole 24-hour days between two absolute instants. */
+export function daysBetween(earlierMs, laterMs) {
+    if (!Number.isFinite(earlierMs) || !Number.isFinite(laterMs)) {
+        return 0;
+    }
+    const diff = laterMs - earlierMs;
+    if (diff <= 0) {
+        return 0;
+    }
+    return Math.floor(diff / ONE_DAY_MS);
+}
+/**
+ * Map days-idle to the stage we'd like to have sent by now.
+ *
+ * Returns `null` when no nudge is wanted at this idle level.
+ */
+export function computeTargetStage(daysIdle) {
+    if (daysIdle < 7) {
+        return null;
+    }
+    if (daysIdle < 14) {
+        return 1;
+    }
+    if (daysIdle < 30) {
+        return 2;
+    }
+    return 3;
+}
+const ACTIVE_HOURS_TIME_PATTERN = /^(?:([01]\d|2[0-3]):([0-5]\d)|24:00)$/;
+function resolveUserTimezone(cfg) {
+    const configured = cfg?.agents?.defaults?.userTimezone;
+    if (typeof configured === "string") {
+        const trimmed = configured.trim();
+        if (trimmed) {
+            try {
+                new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).format(new Date());
+                return trimmed;
+            }
+            catch {
+                // Fall through to the host timezone below.
+            }
+        }
+    }
+    return Intl.DateTimeFormat().resolvedOptions().timeZone?.trim() || "UTC";
+}
+function resolveActiveHoursTimezone(cfg, raw) {
+    const trimmed = typeof raw === "string" ? raw.trim() : "";
+    if (!trimmed || trimmed === "user") {
+        return resolveUserTimezone(cfg);
+    }
+    if (trimmed === "local") {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone?.trim() || "UTC";
+    }
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).format(new Date());
+        return trimmed;
+    }
+    catch {
+        return resolveUserTimezone(cfg);
+    }
+}
+function parseActiveHoursTime(raw, opts) {
+    if (typeof raw !== "string") {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (!ACTIVE_HOURS_TIME_PATTERN.test(trimmed)) {
+        return null;
+    }
+    const [hourStr, minuteStr] = trimmed.split(":");
+    const hour = Number(hourStr);
+    const minute = Number(minuteStr);
+    if (!Number.isFinite(hour) || !Number.isFinite(minute)) {
+        return null;
+    }
+    if (hour === 24) {
+        if (!opts.allow24 || minute !== 0) {
+            return null;
+        }
+        return 24 * 60;
+    }
+    return hour * 60 + minute;
+}
+/**
+ * Return a trimmed `HH:MM` time string from `raw` if it parses against
+ * `parseActiveHoursTime`. Returns `null` when `raw` is unset, empty, or
+ * malformed. Callers use the `null` case to fall through to a lower-
+ * precedence tier's value for that field.
+ */
+function overlayActiveHoursTime(raw, opts) {
+    if (typeof raw !== "string") {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (parseActiveHoursTime(trimmed, opts) == null) {
+        return null;
+    }
+    return trimmed;
+}
+/**
+ * Return an IANA timezone from `raw` when the user has explicitly set
+ * the `nudgeActiveHoursTimezone` key to a valid zone or keyword
+ * (`"user"` / `"local"`). Returns `null` when unset or malformed — the
+ * caller falls through to the baseline timezone in that case.
+ */
+function overlayActiveHoursTimezone(cfg, raw) {
+    if (typeof raw !== "string") {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (trimmed === "user") {
+        return resolveUserTimezone(cfg);
+    }
+    if (trimmed === "local") {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone?.trim() || null;
+    }
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).format(new Date());
+        return trimmed;
+    }
+    catch {
+        return null;
+    }
+}
+function activeHoursFromShape(cfg, raw) {
+    if (!raw) {
+        return null;
+    }
+    const start = typeof raw.start === "string" ? raw.start.trim() : undefined;
+    const end = typeof raw.end === "string" ? raw.end.trim() : undefined;
+    if (!start || !end) {
+        return null;
+    }
+    if (parseActiveHoursTime(start, { allow24: false }) == null ||
+        parseActiveHoursTime(end, { allow24: true }) == null) {
+        return null;
+    }
+    return {
+        start,
+        end,
+        timezone: resolveActiveHoursTimezone(cfg, raw.timezone),
+    };
+}
+function activeHoursFromChannelsTlon(cfg) {
+    const tlon = cfg?.channels?.tlon;
+    const raw = tlon?.nudgeActiveHours;
+    if (!raw || typeof raw !== "object") {
+        return null;
+    }
+    return activeHoursFromShape(cfg, raw);
+}
+function activeHoursFromFileConfig(cfg) {
+    const agentsDefaults = cfg?.agents?.defaults?.heartbeat?.activeHours;
+    if (!agentsDefaults || typeof agentsDefaults !== "object") {
+        return null;
+    }
+    return activeHoursFromShape(cfg, agentsDefaults);
+}
+/**
+ * Four-tier fallback for active hours, applied as a field-wise overlay:
+ *   1. Settings store keys (`nudgeActiveHours*`) — runtime-tunable via
+ *      %settings. Each of `start` / `end` / `timezone` is overlaid
+ *      individually over the baseline below; a partial settings edit
+ *      (e.g. timezone-only, or single bound) takes effect without
+ *      forcing operators to rewrite the full triple.
+ *   2. Plugin file config at `cfg.channels.tlon.nudgeActiveHours` — a
+ *      first-class static override for deployments that want the plugin
+ *      scheduler to run on a fixed window without reusing the legacy
+ *      heartbeat block.
+ *   3. Backwards-compat at `cfg.agents.defaults.heartbeat.activeHours` —
+ *      preserves behavior for tlawn.py-generated hosted configs that set
+ *      the legacy heartbeat block.
+ *   4. Hard-coded defaults (`09:00`–`21:00`, `America/New_York`).
+ *
+ * Malformed settings values (bad `HH:MM`, unknown timezone) fall
+ * through to the baseline for that specific field, so a broken
+ * individual key cannot promote a broken settings tier over a valid
+ * lower-precedence configuration.
+ */
+export function resolveActiveHours(settings, cfg) {
+    const baseline = activeHoursFromChannelsTlon(cfg) ??
+        activeHoursFromFileConfig(cfg) ?? {
+        start: DEFAULT_ACTIVE_HOURS_START,
+        end: DEFAULT_ACTIVE_HOURS_END,
+        timezone: DEFAULT_ACTIVE_HOURS_TIMEZONE,
+    };
+    const startOverride = overlayActiveHoursTime(settings.nudgeActiveHoursStart, { allow24: false });
+    const endOverride = overlayActiveHoursTime(settings.nudgeActiveHoursEnd, {
+        allow24: true,
+    });
+    const timezoneOverride = overlayActiveHoursTimezone(cfg, settings.nudgeActiveHoursTimezone);
+    return {
+        start: startOverride ?? baseline.start,
+        end: endOverride ?? baseline.end,
+        timezone: timezoneOverride ?? baseline.timezone,
+    };
+}
+/**
+ * Derive "HH:MM" for `date` in the given IANA timezone.
+ */
+function formatLocalHhMm(date, timezone) {
+    const fmt = new Intl.DateTimeFormat("en-GB", {
+        timeZone: timezone,
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+    });
+    const parts = fmt.formatToParts(date);
+    let hh = "00";
+    let mm = "00";
+    for (const part of parts) {
+        if (part.type === "hour") {
+            hh = part.value;
+        }
+        if (part.type === "minute") {
+            mm = part.value;
+        }
+    }
+    // `Intl.DateTimeFormat` with `hour12: false` can yield "24:00" at midnight
+    // on some engines; normalize to "00:00" for comparison consistency.
+    if (hh === "24") {
+        hh = "00";
+    }
+    return `${hh}:${mm}`;
+}
+function resolveMinutesInTimeZone(date, timezone) {
+    const local = formatLocalHhMm(date, timezone);
+    const [hourStr, minuteStr] = local.split(":");
+    const hour = Number(hourStr);
+    const minute = Number(minuteStr);
+    if (!Number.isFinite(hour) || !Number.isFinite(minute)) {
+        return null;
+    }
+    return hour * 60 + minute;
+}
+/**
+ * `true` when `date` falls inside `[start, end)` in the configured timezone.
+ * Supports wrap-around windows (e.g. `22:00`–`06:00`).
+ */
+export function inActiveHours(date, activeHours) {
+    const startMin = parseActiveHoursTime(activeHours.start, { allow24: false });
+    const endMin = parseActiveHoursTime(activeHours.end, { allow24: true });
+    if (startMin == null || endMin == null) {
+        return true;
+    }
+    if (startMin === endMin) {
+        // Match OpenClaw heartbeat semantics: equal bounds form a zero-width
+        // window, so scheduled work is always outside the active window.
+        return false;
+    }
+    const now = resolveMinutesInTimeZone(date, activeHours.timezone);
+    if (now == null) {
+        return true;
+    }
+    if (endMin > startMin) {
+        return now >= startMin && now < endMin;
+    }
+    // Wrap-around: e.g. 22:00 – 06:00.
+    return now >= startMin || now < endMin;
+}
+/**
+ * Resolve the most authoritative last-owner-activity timestamp (epoch ms).
+ *
+ * Prefers the synchronous in-memory shadow over the settings mirror, since
+ * the shadow is updated the moment the owner-reply handler observes a
+ * message and cannot lag behind a subscription-delivered clear.
+ */
+export function resolveLastOwnerInstant(shadow, settings) {
+    if (shadow && typeof shadow.at === "number" && Number.isFinite(shadow.at)) {
+        return shadow.at;
+    }
+    if (typeof settings.lastOwnerMessageAt === "number") {
+        return settings.lastOwnerMessageAt;
+    }
+    if (typeof settings.lastOwnerMessageDate === "string") {
+        const parsed = Date.parse(settings.lastOwnerMessageDate);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+export function shouldSend(inputs) {
+    if (inputs.targetStage == null) {
+        return false;
+    }
+    if (!inputs.ownerShip) {
+        return false;
+    }
+    if (!inputs.isInActiveHours) {
+        return false;
+    }
+    return inputs.targetStage > inputs.lastNudgeStage;
+}
+//# sourceMappingURL=nudge-decision.js.map

package/dist/src/nudge-decision.js.map

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

package/dist/src/nudge-messages.js

@@ -0,0 +1,25 @@
+/**
+ * Canonical re-engagement nudge messages, keyed by stage.
+ *
+ * Moved from the LLM-owned prompt (`tlonbot/prompts/HEARTBEAT.md`) into the
+ * plugin so the plugin is the single source of truth for nudge content.
+ */
+export const NUDGE_MESSAGES = {
+    1: "Hey! Quick ideas for your week:\n" +
+        '• "Make me a group about cooking" — I\'ll set it up, then give you a link to invite your friends\n' +
+        '• "Tell me the weather every morning at 8am"\n' +
+        '• "Send me a daily digest with breaking news about AI"\n\n' +
+        "Just reply with any of these or ask me anything 🌱",
+    2: "A few things I can do for you:\n" +
+        "• Create a group — tell me what you're into and I'll set it up. Invite your friends and get a conversation going.\n" +
+        '• Run recurring jobs — "track AAPL and tell me if it moves more than 5%", "summarize the news every morning", "help me track my meals"\n' +
+        "• Watch a channel and ping you when something important comes up\n\n" +
+        "What sounds useful?",
+    3: "Still here! Here's what I can do:\n\n" +
+        "**Groups** — I'll create groups for you, help brainstorm ideas, and manage permissions. Invite your friends and hang out.\n" +
+        "**Recurring jobs** — daily weather, news alerts, meal tracking, stock tracking, scheduled reminders — just tell me what and when.\n" +
+        "**Catch up** — summarize threads, watch channels for keywords\n" +
+        "**Research** — web search, fact-check, find recipes/flights/etc.\n\n" +
+        "Just say the word 🌱",
+};
+//# sourceMappingURL=nudge-messages.js.map

package/dist/src/nudge-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge-messages.js","sourceRoot":"","sources":["../../src/nudge-messages.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,CAAC,MAAM,cAAc,GAA+B;IACxD,CAAC,EACC,mCAAmC;QACnC,oGAAoG;QACpG,gDAAgD;QAChD,4DAA4D;QAC5D,oDAAoD;IACtD,CAAC,EACC,kCAAkC;QAClC,qHAAqH;QACrH,0IAA0I;QAC1I,sEAAsE;QACtE,qBAAqB;IACvB,CAAC,EACC,uCAAuC;QACvC,6HAA6H;QAC7H,qIAAqI;QACrI,iEAAiE;QACjE,sEAAsE;QACtE,sBAAsB;CACzB,CAAC"}

package/dist/src/nudge-scheduler.js

@@ -0,0 +1,91 @@
+/**
+ * Interval-driven scheduler for re-engagement nudge ticks.
+ *
+ * Owns the timer lifecycle, reentrancy guard, and abort handling. Knows
+ * nothing about Urbit, settings, or telemetry — the caller supplies a
+ * tick callback that does the evaluation and side effects.
+ */
+export const DEFAULT_NUDGE_TICK_INTERVAL_MS = 15 * 60 * 1000;
+export function createNudgeScheduler(opts) {
+    const intervalMs = opts.intervalMs ?? DEFAULT_NUDGE_TICK_INTERVAL_MS;
+    let timer = null;
+    let running = false;
+    let started = false;
+    // Tracked so `stop()` can await an in-flight tick before the caller
+    // tears down the rest of the monitor (persistence queues, `api.close()`
+    // etc.). Cleared inside the tick's `finally` once the body resolves.
+    let activeTick = null;
+    async function runTick() {
+        if (opts.abortSignal?.aborted) {
+            return;
+        }
+        if (running) {
+            return;
+        }
+        running = true;
+        const task = (async () => {
+            try {
+                await opts.tick();
+            }
+            catch (err) {
+                opts.error?.(`[tlon] nudge tick failed: ${String(err)}`);
+            }
+            finally {
+                running = false;
+            }
+        })();
+        activeTick = task;
+        try {
+            await task;
+        }
+        finally {
+            if (activeTick === task) {
+                activeTick = null;
+            }
+        }
+    }
+    return {
+        start() {
+            if (started) {
+                return;
+            }
+            if (opts.abortSignal?.aborted) {
+                return;
+            }
+            started = true;
+            // Schedule the first tick on the next macrotask so callers can finish
+            // their synchronous startup wiring before the tick observes state.
+            setTimeout(() => {
+                if (opts.abortSignal?.aborted || !started) {
+                    return;
+                }
+                void runTick();
+            }, 0);
+            timer = setInterval(() => {
+                if (opts.abortSignal?.aborted) {
+                    return;
+                }
+                void runTick();
+            }, intervalMs);
+        },
+        async stop() {
+            started = false;
+            if (timer != null) {
+                clearInterval(timer);
+                timer = null;
+            }
+            // Drain any in-flight tick so shutdown-time cleanup (queue flush,
+            // shadow clear, api.close) runs after the tick's last writes land.
+            if (activeTick) {
+                await activeTick.catch(() => undefined);
+            }
+        },
+        async tickNow() {
+            await runTick();
+        },
+        get isRunning() {
+            return running;
+        },
+    };
+}
+//# sourceMappingURL=nudge-scheduler.js.map

package/dist/src/nudge-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge-scheduler.js","sourceRoot":"","sources":["../../src/nudge-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAsB7D,MAAM,UAAU,oBAAoB,CAAC,IAA2B;IAC9D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,8BAA8B,CAAC;IACrE,IAAI,KAAK,GAA0B,IAAI,CAAC;IACxC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,oEAAoE;IACpE,wEAAwE;IACxE,qEAAqE;IACrE,IAAI,UAAU,GAAyB,IAAI,CAAC;IAE5C,KAAK,UAAU,OAAO;QACpB,IAAI,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC;YAAA,OAAO;QAAA,CAAC;QACxC,IAAI,OAAO,EAAE,CAAC;YAAA,OAAO;QAAA,CAAC;QACtB,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,IAAI,GAAG,CAAC,KAAK,IAAI,EAAE;YACvB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,KAAK,EAAE,CAAC,6BAA6B,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC3D,CAAC;oBAAS,CAAC;gBACT,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QACL,UAAU,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC;QACb,CAAC;gBAAS,CAAC;YACT,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;gBACxB,UAAU,GAAG,IAAI,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK;YACH,IAAI,OAAO,EAAE,CAAC;gBAAA,OAAO;YAAA,CAAC;YACtB,IAAI,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC;gBAAA,OAAO;YAAA,CAAC;YACxC,OAAO,GAAG,IAAI,CAAC;YACf,sEAAsE;YACtE,mEAAmE;YACnE,UAAU,CAAC,GAAG,EAAE;gBACd,IAAI,IAAI,CAAC,WAAW,EAAE,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;oBAAA,OAAO;gBAAA,CAAC;gBACpD,KAAK,OAAO,EAAE,CAAC;YACjB,CAAC,EAAE,CAAC,CAAC,CAAC;YACN,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;gBACvB,IAAI,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC;oBAAA,OAAO;gBAAA,CAAC;gBACxC,KAAK,OAAO,EAAE,CAAC;YACjB,CAAC,EAAE,UAAU,CAAC,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,IAAI;YACR,OAAO,GAAG,KAAK,CAAC;YAChB,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;gBAClB,aAAa,CAAC,KAAK,CAAC,CAAC;gBACrB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;YACD,kEAAkE;YAClE,mEAAmE;YACnE,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;QACD,KAAK,CAAC,OAAO;YACX,MAAM,OAAO,EAAE,CAAC;QAClB,CAAC;QACD,IAAI,SAAS;YACX,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/pending-nudge.js

@@ -0,0 +1,57 @@
+/**
+ * Pending nudge shared state for heartbeat re-engagement attribution.
+ *
+ * When the plugin-driven scheduler sends a re-engagement nudge, a
+ * PendingNudge record is stored here. If the owner replies within the
+ * attribution window, the monitor emits a re-engagement event, injects the
+ * nudge content as context for the agent, and clears the record.
+ *
+ * Keyed by accountId — each account has at most one pending nudge at a
+ * time. Per-account persist callbacks route writes to the correct ship's
+ * settings store.
+ */
+/** Default re-engagement attribution window: 72 hours */
+export const DEFAULT_ATTRIBUTION_WINDOW_MS = 72 * 60 * 60 * 1000;
+const pendingNudges = new Map();
+const persistCallbacks = new Map();
+export function setPendingNudge(accountId, nudge) {
+    pendingNudges.set(accountId, nudge);
+    persistCallbacks.get(accountId)?.(nudge);
+}
+export function getPendingNudge(accountId) {
+    return pendingNudges.get(accountId) ?? null;
+}
+export function clearPendingNudge(accountId) {
+    pendingNudges.delete(accountId);
+    persistCallbacks.get(accountId)?.(null);
+}
+export function registerPersistCallback(accountId, cb) {
+    persistCallbacks.set(accountId, cb);
+}
+/**
+ * Sync from settings store (startup load or hot-reload).
+ * Does NOT trigger persist callback — the data came from the store.
+ */
+export function syncPendingNudgeFromStore(accountId, nudge) {
+    if (nudge) {
+        pendingNudges.set(accountId, nudge);
+    }
+    else {
+        pendingNudges.delete(accountId);
+    }
+}
+/**
+ * Returns true if the pending nudge is still within the attribution window.
+ * @param nowMs - current time in epoch ms (injectable for tests)
+ * @param windowMs - attribution window in ms (overridable, defaults to 72h)
+ */
+export function isNudgeEligible(nudge, nowMs = Date.now(), windowMs = DEFAULT_ATTRIBUTION_WINDOW_MS) {
+    return nowMs - nudge.sentAt <= windowMs;
+}
+export const _testing = {
+    clearAll: () => {
+        pendingNudges.clear();
+        persistCallbacks.clear();
+    },
+};
+//# sourceMappingURL=pending-nudge.js.map

package/dist/src/pending-nudge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-nudge.js","sourceRoot":"","sources":["../../src/pending-nudge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,yDAAyD;AACzD,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjE,MAAM,aAAa,GAAG,IAAI,GAAG,EAAwB,CAAC;AACtD,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAgD,CAAC;AAEjF,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,KAAmB;IACpE,aAAa,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACpC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAChC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,SAAiB,EACjB,EAAwC;IAExC,gBAAgB,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAiB,EAAE,KAA0B;IACrF,IAAI,KAAK,EAAE,CAAC;QACV,aAAa,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAmB,EACnB,QAAgB,IAAI,CAAC,GAAG,EAAE,EAC1B,WAAmB,6BAA6B;IAEhD,OAAO,KAAK,GAAG,KAAK,CAAC,MAAM,IAAI,QAAQ,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,QAAQ,EAAE,GAAG,EAAE;QACb,aAAa,CAAC,KAAK,EAAE,CAAC;QACtB,gBAAgB,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;CACF,CAAC"}

package/dist/src/settings.js

@@ -36,6 +36,54 @@ function parseChannelRules(value) {
     }
     return undefined;
 }
+/**
+ * Parse pendingNudge — handles both JSON string and object formats.
+ * Settings-store stores complex objects as JSON strings.
+ */
+function parsePendingNudge(value) {
+    if (!value) {
+        return undefined;
+    }
+    let parsed = value;
+    if (typeof value === "string") {
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return undefined;
+    }
+    const obj = parsed;
+    if (typeof obj.sentAt !== "number" ||
+        typeof obj.ownerShip !== "string" ||
+        typeof obj.accountId !== "string" ||
+        !(obj.stage === 1 || obj.stage === 2 || obj.stage === 3)) {
+        return undefined;
+    }
+    const base = {
+        sentAt: obj.sentAt,
+        stage: obj.stage,
+        ownerShip: obj.ownerShip,
+        accountId: obj.accountId,
+    };
+    if (typeof obj.content === "string") {
+        base.content = obj.content;
+    }
+    return base;
+}
+/**
+ * Parse lastNudgeStage — accepts number or numeric string, must be 1, 2, or 3.
+ */
+function parseLastNudgeStage(value) {
+    const num = typeof value === "string" ? Number(value) : value;
+    if (num === 1 || num === 2 || num === 3) {
+        return num;
+    }
+    return undefined;
+}
 /**
  * Parse settings from the raw Urbit settings-store response.
  * The response shape is: { [bucket]: { [key]: value } }
@@ -74,6 +122,15 @@ export function parseSettingsResponse(raw) {
         pendingApprovals: parsePendingApprovals(settings.pendingApprovals),
         lastOwnerMessageAt: typeof settings.lastOwnerMessageAt === "number" ? settings.lastOwnerMessageAt : undefined,
         lastOwnerMessageDate: typeof settings.lastOwnerMessageDate === "string" ? settings.lastOwnerMessageDate : undefined,
+        pendingNudge: parsePendingNudge(settings.pendingNudge),
+        lastNudgeStage: parseLastNudgeStage(settings.lastNudgeStage),
+        nudgeActiveHoursStart: typeof settings.nudgeActiveHoursStart === "string"
+            ? settings.nudgeActiveHoursStart
+            : undefined,
+        nudgeActiveHoursEnd: typeof settings.nudgeActiveHoursEnd === "string" ? settings.nudgeActiveHoursEnd : undefined,
+        nudgeActiveHoursTimezone: typeof settings.nudgeActiveHoursTimezone === "string"
+            ? settings.nudgeActiveHoursTimezone
+            : undefined,
     };
 }
 function isChannelRulesObject(val) {
@@ -210,6 +267,21 @@ export function applySettingsUpdate(current, key, value) {
         case "lastOwnerMessageDate":
             next.lastOwnerMessageDate = typeof value === "string" ? value : undefined;
             break;
+        case "pendingNudge":
+            next.pendingNudge = parsePendingNudge(value);
+            break;
+        case "lastNudgeStage":
+            next.lastNudgeStage = parseLastNudgeStage(value);
+            break;
+        case "nudgeActiveHoursStart":
+            next.nudgeActiveHoursStart = typeof value === "string" ? value : undefined;
+            break;
+        case "nudgeActiveHoursEnd":
+            next.nudgeActiveHoursEnd = typeof value === "string" ? value : undefined;
+            break;
+        case "nudgeActiveHoursTimezone":
+            next.nudgeActiveHoursTimezone = typeof value === "string" ? value : undefined;
+            break;
     }
     return next;
 }
@@ -262,14 +334,14 @@ export function createSettingsManager(api, logger) {
                 state.current = parseSettingsResponse(deskData ?? {});
                 state.loaded = true;
                 logger?.log?.(`[settings] Loaded: ${JSON.stringify(state.current)}`);
-                return state.current;
+                return { settings: state.current, fresh: true };
             }
             catch (err) {
-                // Settings desk may not exist yet - that's fine, use defaults
-                logger?.log?.(`[settings] No settings found (using defaults): ${String(err)}`);
-                state.current = {};
+                // Preserve the last good snapshot on scry failure so refresh fallback
+                // does not transiently clobber live runtime state with an empty object.
+                logger?.log?.(`[settings] Load failed (keeping previous settings): ${String(err)}`);
                 state.loaded = true;
-                return state.current;
+                return { settings: state.current, fresh: false };
             }
         },
         /**