Skip to content
← Public packages

@kentcdodds/quiet-hours

Quiet hours for Kent's bots: 10 PM to 8 AM MT (DST-aware) clock, shared overnight queue, override, and the 8 AM digest of finished work and open decisions.

FollowFork

Files

AGENTS.md

91 lines · 6.1 KB · Markdown

@kentcdodds/quiet-hours: agent notes

Imports

import status from 'kody:@kentcdodds/quiet-hours/status'
import queue from 'kody:@kentcdodds/quiet-hours/queue'
import override from 'kody:@kentcdodds/quiet-hours/override'
import list from 'kody:@kentcdodds/quiet-hours/list'
import digest from 'kody:@kentcdodds/quiet-hours/digest'
import fallbackDigest from 'kody:@kentcdodds/quiet-hours/fallback-digest'
ExportSignatureWrites?
status(input?: { bot?: string; now?: string }) => Promise<{ quiet: boolean; until: string; override: QuietOverride | null; excluded?: true; degraded?: true }>no
queue(input: { bot; kind: 'done' | 'needs-decision' | 'fyi' | 'kent-request'; priority?: 'urgent' | 'high' | 'normal' | 'low'; title; link?; detail?; deadline?: ISO }) => Promise<{ ok; queued; item; waitingOnMe }>yes
override(input: { mode: 'on' | 'off' | 'clear'; by?: string } | 'on' | 'off' | 'clear') => Promise<{ ok; mode; override; status }>yes
list() => Promise<{ count; since: string | null; lastDigest; items }>no
digest(input?: { dryRun?: boolean; via?: string }) => Promise<{ digestId; deliveredAt; counts; buckets; items; text }>yes, marks delivered
fallback-digest(input?: { dryRun?; force?; channelId? }) => Promise<...> (job entry)yes, posts to Discord

until is when the current state ends: the next 8 AM while quiet, the next 10 PM while not, or the override's expiresAt while one is active. Every export accepts now (an ISO string) for tests and previews.

Overnight rule for bots

  1. Call status({ bot }). If quiet is false, behave normally.
  2. Work that doesn't need Kent: keep going. When it finishes, queue({ kind: 'done', ... }).
  3. Work that needs Kent's input and isn't urgent: stop there and queue({ kind: 'needs-decision', link, ... }). needs-decision is the main waiting state.
  4. Only urgent items break through. Urgent means all three of: prod down, a security or money-at-risk event, or a hard deadline before 9 AM; harm that grows before 8 AM; and Kent is actually needed.
  5. kent-request is still accepted for compatibility, but it's mostly unnecessary. If Kent asked for something, either do it (it doesn't need him) or queue the open decision. The digest treats it as fyi.

Digest buckets (in order)

The digest reports finished work and open decisions. It isn't a backlog to kick off.

OrderBucketRule (checked top to bottom)
1urgent-resolvedpriority: 'urgent' and kind done / fyi / kent-request
2deadline-todaykind is not done and deadline falls on the digest's Denver date or earlier
3decisionkind needs-decision
4fyieverything else: done, fyi, kent-request

Within a bucket, items sort by priority (urgent > high > normal > low), then earliest deadline, then oldest first. digest() marks every returned item delivered and records last-digest, even when the digest is empty. Use dryRun: true to preview.

Waiting on Me mirror

needs-decision items are mirrored to kody:@kentcdodds/waiting-on-me/create with: nativeId/idempotencyKey = quiet-hours:<itemId>, title = "<bot>: <title>", summary = detail || title, actionUrl = link (which is why link is required for needs-decision), and urgency mapped urgent→critical, high→high, normal→medium, low→low. deadline and actor: 'agent' are also passed. The mirror never fails the queue call. Its result is stored on the item (waitingOnMe: { ok, id } | { ok: false, error } ).

Why execute, not a static import: @kentcdodds/discord and @kentcdodds/grok-bot statically import quiet-hours/status, and waiting-on-me depends on grok-bot. A static kody:@ import of waiting-on-me or discord from here would create a kody.dependencies cycle, which publish rejects. So src/cross-package.ts calls kody.execute with a literal import create from 'kody:@kentcdodds/waiting-on-me/create' module, the same pattern discord uses to wake grok-bot. This package has no kody.dependencies.

Fallback job

  • kody.jobs.fallback-digest: cron 15 8 * * *, timezone: "America/Denver", enabled: false. The platform evaluates cron in that zone, so 8:15 stays 8:15 across DST. The job also skips itself while the clock still says quiet, as a guard if someone moves it to UTC.
  • It skips when last-digest.at is at or after the most recent 10 PM MT. Otherwise it posts digest text to Discord (default #reports 1530233790516039881, or override it via the settings.fallbackChannelId state row or the channelId input) and then marks those items delivered. If the post fails, nothing is marked delivered.
  • Smoke test without side effects:
import fallbackDigest from 'kody:@kentcdodds/quiet-hours/fallback-digest'
export default async () => fallbackDigest({ dryRun: true, force: true })

Smoke tests

import status from 'kody:@kentcdodds/quiet-hours/status'
export default async () => ({
	now: await status(),
	fallBack: await status({ now: '2026-11-01T04:00:00Z' }), // until 2026-11-01T15:00Z (8 AM MST)
	springFwd: await status({ now: '2027-03-14T05:00:00Z' }), // until 2027-03-14T14:00Z (8 AM MDT)
	lilly: await status({ bot: 'Lilly' }),
})
import digest from 'kody:@kentcdodds/quiet-hours/digest'
export default async () => digest({ dryRun: true })

Edge cases

  • Excluded bots: lilly and imogen (case-insensitive). queue returns { queued: false, excluded: true }, and status returns { quiet: false, excluded: true }.
  • If storage is unreachable, status still answers from the clock and sets degraded: true.
  • override('on') set during the day lasts until the next 8 AM, which means it covers that night too.
  • This package makes no direct fetch calls. Any fetch added later must send x-kody-secret-resolution: headers-only. A test enforces this.
  • Storage: packageStorage().sql tables quiet_items and quiet_state (override, last-digest, settings).

Local tests

npm test uses Node 24 with node:sqlite and the test/kody-mocks.mjs hooks. Typecheck runs from the repo tsconfig.json, which also turns on Kody's publish typecheck.