# @kentcdodds/quiet-hours: agent notes ## Imports ```ts 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' ``` | Export | Signature | Writes? | | --- | --- | --- | | `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. | Order | Bucket | Rule (checked top to bottom) | | --- | --- | --- | | 1 | `urgent-resolved` | `priority: 'urgent'` and kind `done` / `fyi` / `kent-request` | | 2 | `deadline-today` | kind is not `done` and `deadline` falls on the digest's Denver date or earlier | | 3 | `decision` | kind `needs-decision` | | 4 | `fyi` | everything 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:`, `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: ```ts import fallbackDigest from 'kody:@kentcdodds/quiet-hours/fallback-digest' export default async () => fallbackDigest({ dryRun: true, force: true }) ``` ## Smoke tests ```ts 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' }), }) ``` ```ts 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.