Engagement

ScalyClaw can reach out first when something actionable happens. The proactive system turns ambient signals — pending task results, deadlines in memory, an idle conversation, a user returning from absence — into at most one message per scan, broadcast to every enabled channel. Everything runs in the background via the scalyclaw-internal queue, evaluated by a single LLM call per firing.

Lifecycle

Each tick of the cron pattern runs this pipeline:

1. Signal scan — six independent detectors run in parallel (Redis + SQLite reads only, no LLM). Any detector may return a Signal with a strength in [0, 1].
2. Aggregate — the detected signals collapse into a single Trigger. Priority picks the trigger type (e.g. an urgent signal always wins over a check_in), and a weighted sum gives the aggregate strength.
3. Adaptive threshold — the trigger must exceed a self-tuning threshold. During cold start (fewer than 5 proactive messages ever sent) the threshold is the midpoint of adaptiveRange; afterwards it shifts down when the user engages with proactive messages and up when they ignore them.
4. Timing gate — checks workflow phase (active/post-task/idle/deep-idle), mute state, quiet hours (with urgentOverride), and low-activity hour throttling. Non-urgent signals are buffered and retried later.
5. Deep evaluation — enqueues a proactive-eval job. The job re-detects signals (rate-limit + daily-cap recheck), assembles context, and runs one LLM call that either decides to stay quiet or returns a ready-to-send message.
6. Broadcast delivery — the message is sent to every enabled channel adapter in parallel. There is no "best channel" heuristic; the cross-channel philosophy applies.
7. Bookkeeping — after at least one channel delivers successfully: start per-trigger cooldown, increment daily counter, record one proactive_events row per delivered channel, store the message in the SQLite messages table with source: "proactive". On total delivery failure nothing is recorded — the next tick can retry.

Signals

Six detectors produce signals. Any of them can be the sole reason for a firing.

Trigger types

Signals collapse into one of four trigger types. The highest-priority type wins when multiple signals fire at once. Each type has its own cooldown.

Adaptive threshold

The aggregate trigger strength is gated by an adaptive threshold that self-tunes to how the user reacts:

// profile.totalSent < 5 → cold start, use midpoint
threshold = (adaptiveRange.min + adaptiveRange.max) / 2

// otherwise, tune with engagement rate
engagementRate = profile.totalEngaged / profile.totalSent
threshold      = adaptiveRange.max - engagementRate * (adaptiveRange.max - adaptiveRange.min)

High engagement → lower threshold → more proactive. Ignored messages → higher threshold → less proactive. Defaults: adaptiveRange.min = 0.3, adaptiveRange.max = 0.9, so a fresh install starts at 0.6.

Timing

Even when a trigger passes the threshold, the timing gate may still defer or suppress delivery.

• Workflow phase — active (<5 min since last user msg) blocks; post_task (5–30 min) is the optimal window; idle (30 min–2 h) and deep_idle (≥2 h) both allow.
• Mute — POST /api/proactive/mute sets profile.mutedUntil. Respected unconditionally until it expires.
• Quiet hours — if quietHours.enabled and the current hour (in quietHours.timezone) is inside the window, non-urgent triggers are dropped. urgent triggers bypass when quietHours.urgentOverride: true.
• Low-activity hour — if the current hour sits below 30% of the user's average activity (and there is enough data to judge), non-urgent triggers are delayed 30 min.
• Signal buffering — when timing defers delivery, the detected signals are buffered under Redis key scalyclaw:proactive:signals with TTL equal to suggestedDelayMinutes, so the next tick can pick them up cheaply.

Channel delivery

Proactive messages are broadcast to every enabled channel adapter in parallel. There is no "primary" or "best" channel — the philosophy is cross-channel: if you enabled Telegram, Discord, and Slack, a proactive message lands on all three. The gateway adapter (used by the dashboard chat UI) also receives it.

Delivery uses Promise.allSettled, so one adapter failing never blocks the others. After the cycle:

• If at least one channel accepted the message, bookkeeping runs exactly once — cooldown is set, daily counter is incremented, and one proactive_events row is inserted per delivered channel (so per-channel user response tracking works: a response on Discord resolves only that channel's event).
• If every channel failed, nothing is recorded — the next tick is free to retry.

Config reference

Every field below is stored in Redis at scalyclaw:config under proactive and is editable from the dashboard Engagement page (hot-reload, no restart).

// Full proactive config under scalyclaw:config
{
  "proactive": {
    "enabled": true,
    "model": "",
    "monitorCronPattern": "*/5 * * * *",
    "signals": {
      "idleThresholdMinutes": 120,
      "idleMaxDays": 7,
      "timeSensitiveLeadMinutes": 60,
      "returnFromAbsenceHours": 24
    },
    "engagement": {
      "baseThreshold": 0.6,
      "responseWindowMinutes": 60,
      "adaptiveRange": { "min": 0.3, "max": 0.9 }
    },
    "rateLimits": {
      "cooldownSeconds": {
        "urgent": 1800,
        "deliverable": 7200,
        "insight": 28800,
        "check_in": 43200
      },
      "maxPerDay": 5,
      "maxUrgentPerDay": 10
    },
    "quietHours": {
      "enabled": true,
      "start": 22,
      "end": 8,
      "timezone": "UTC",
      "urgentOverride": true
    },
    "triggerWeights": {
      "urgent": 1.0,
      "deliverable": 0.9,
      "insight": 0.5,
      "check_in": 0.3
    }
  }
}

Admin API

The dashboard Engagement page is backed by these endpoints. Raw curl is fine too.

Why isn't it firing?

When proactive messages aren't arriving, work through the log lines the engine emits during a scan:

The quickest way to force the path is POST /api/proactive/trigger (or the "Trigger now" button on the dashboard). It shares the exact same pipeline as the cron scan, so whatever blocks the button blocks the cron too.