@gotcos/glasses-server 6.42.1 → 6.43.0

package/server/lib/morning-brief-prompt.ts

@@ -0,0 +1,263 @@
+// Morning brief — the prompt composer.
+//
+// Pure: config + clock in, one prompt string out. The prompt is what the user's
+// own COS agent receives as a durable query job at the scheduled minute, so it
+// carries everything the agent needs and nothing the server cannot vouch for:
+//
+//  - the read-only contract (nobody is watching; never send, create, or edit);
+//  - the sections, in the user's order, each with its window and its own
+//    "unavailable" rule so a missing connector produces one honest line, not a
+//    fabricated one;
+//  - the glasses formatting contract (plain text, short labelled lines) so the
+//    result renders on a 576x288 lens without a second pass.
+//
+// Deterministic for a given (config, day): the scheduled slot, not the actual
+// firing minute, is what appears in the prompt. That is what lets a retry after
+// a crashed submission re-admit as the SAME job by client identity instead of
+// conflicting on a different prompt body.
+
+import type { MorningBriefConfig, MorningBriefSource, MorningBriefSourceId } from './morning-brief-config.js'
+import { MORNING_BRIEF_SOURCES } from './morning-brief-config.js'
+import { parseTime, shiftDay } from './morning-brief-schedule.js'
+
+/** Well under the 48,000-char durable-job ceiling, with room for the largest
+ * legal combination of free-text options. */
+export const MORNING_BRIEF_PROMPT_MAX_CHARS = 16_000
+
+export interface MorningBriefPromptInput {
+  config: MorningBriefConfig
+  /** Local calendar day the brief is for (YYYY-MM-DD in config.timezone). */
+  day: string
+  ownerName: string
+  trigger: 'scheduled' | 'manual'
+}
+
+const WEEKDAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+const MONTH_NAMES = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
+
+function describeDay(day: string): string {
+  const [y, m, d] = day.split('-').map(Number)
+  const weekday = WEEKDAY_NAMES[new Date(Date.UTC(y, m - 1, d)).getUTCDay()]
+  return `${weekday}, ${MONTH_NAMES[m - 1]} ${d}, ${y}`
+}
+
+function lastBusinessDay(day: string): string {
+  let candidate = shiftDay(day, -1)
+  for (let i = 0; i < 7; i++) {
+    const [y, m, d] = candidate.split('-').map(Number)
+    const weekday = new Date(Date.UTC(y, m - 1, d)).getUTCDay()
+    if (weekday !== 0 && weekday !== 6) return candidate
+    candidate = shiftDay(candidate, -1)
+  }
+  return candidate
+}
+
+function plural(n: number, unit: string): string {
+  return `${n} ${unit}${n === 1 ? '' : 's'}`
+}
+
+function str(options: MorningBriefSource['options'], key: string): string {
+  const value = options[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function num(options: MorningBriefSource['options'], key: string, fallback: number): number {
+  const value = options[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+}
+
+function bool(options: MorningBriefSource['options'], key: string, fallback: boolean): boolean {
+  const value = options[key]
+  return typeof value === 'boolean' ? value : fallback
+}
+
+/** One section's instruction. Returns null when the source has nothing to say
+ * (a custom section with no instruction, a skill with no name). */
+export function sectionInstruction(source: MorningBriefSource, day: string): { label: string; body: string } | null {
+  const o = source.options
+  switch (source.id) {
+    case 'calendar':
+      return {
+        label: 'CALENDAR',
+        body: [
+          `Today's commitments in time order, each on one line: start time, title, who it is with when that matters.`,
+          `Name the first commitment of the day and how much open time exists before it.`,
+          bool(o, 'includeTomorrow', false) ? `Then tomorrow's first commitment on one line.` : '',
+          `Read every calendar this workspace can reach (connectors, local calendar helpers, cached calendar files). If none can be read, write "Calendar: unavailable" with the reason.`,
+        ].filter(Boolean).join(' '),
+      }
+    case 'meetings': {
+      const lookback = num(o, 'lookbackDays', 3)
+      const horizon = num(o, 'horizonDays', 7)
+      return {
+        label: 'FROM RECENT MEETINGS',
+        body: [
+          `Meetings synced in the last ${plural(lookback, 'day')} (the last business day before ${day} was ${lastBusinessDay(day)}).`,
+          `Surface only items with a hard edge: a decision that was made, a deadline inside the next ${plural(horizon, 'day')}, a dollar figure, or a named owner.`,
+          `Read the meeting's summary and decisions; never paste an extracted action-item list verbatim, and when a number or date matters, quote it from the transcript.`,
+          `Three to five items ranked by consequence, one line each: the decision or open question, then the hard edge.`,
+          `If nothing decision-grade happened, say so in one line.`,
+        ].join(' '),
+      }
+    }
+    case 'tasks': {
+      const horizon = num(o, 'horizonDays', 7)
+      const overdue = bool(o, 'includeOverdue', true)
+      return {
+        label: 'DUE',
+        body: [
+          `Open tasks from this workspace's task files due within ${plural(horizon, 'day')}${overdue ? ', overdue items first' : ''}.`,
+          `One line each: the task, its owner if not the wearer, and the date. Cap at seven. Skip anything already marked done.`,
+        ].join(' '),
+      }
+    }
+    case 'waiting': {
+      const lookback = num(o, 'lookbackDays', 7)
+      return {
+        label: 'WAITING ON YOU',
+        body: [
+          `Across every channel this workspace can read (Slack, email, chat connectors), from the last ${plural(lookback, 'day')}:`,
+          `direct mentions with no reply from the wearer, questions addressed to the wearer with no answer beneath them, and threads that moved after the wearer's last message.`,
+          `Up to five, ranked by consequence. Each line names the channel or sender, who is waiting, and the ask.`,
+          `Never claim something is unread; report only what is verifiable. If no channel can be read, write "Waiting on you: unavailable" with the reason.`,
+        ].join(' '),
+      }
+    }
+    case 'knowledge': {
+      const lookback = num(o, 'lookbackDays', 7)
+      return {
+        label: 'MOVING',
+        body: [
+          `From memory, threads, and the knowledge graph this workspace keeps: the two or three relationships, projects, or people that moved in the last ${plural(lookback, 'day')} and why it matters today.`,
+          `One line each. Cite the thread or entity by name. Skip this section silently if the workspace has no memory or graph.`,
+        ].join(' '),
+      }
+    }
+    case 'reflection':
+      return {
+        label: 'CARRY THIS',
+        body: [
+          `From recent reflection logs, journal entries, or correction records in this workspace: the one theme that recurs across at least two periods.`,
+          `State the pattern in one line and the single behaviour to carry into today in a second line. Do not grade. Skip silently if there is no reflection history.`,
+        ].join(' '),
+      }
+    case 'health':
+      return {
+        label: 'BODY',
+        body: `Last night's sleep and readiness from any connected health source, one line, with the one adjustment it implies. Skip silently if no health source is connected.`,
+      }
+    case 'reading': {
+      const text = str(o, 'text') || 'proverbs'
+      const [, , d] = day.split('-').map(Number)
+      if (text.toLowerCase() === 'proverbs') {
+        return {
+          label: 'OPENING',
+          body: [
+            `Proverbs chapter ${d} (the calendar day) in the public-domain King James Version, presented as numbered verses.`,
+            `Then one verse from it that genuinely speaks to today's shape, named, with a two-sentence connection. Never substitute a copyrighted translation; if the exact KJV text cannot be verified, say so and skip the chapter.`,
+          ].join(' '),
+        }
+      }
+      return {
+        label: 'OPENING',
+        body: `A short public-domain reading from "${text}" matched to today's date, then one line on why it fits. Never reproduce copyrighted text.`,
+      }
+    }
+    case 'pulse': {
+      const instruction = str(o, 'instruction')
+      return {
+        label: 'PULSE',
+        body: [
+          instruction
+            ? `The numbers the wearer steers by: ${instruction}`
+            : `The numbers the wearer steers by, from any dashboard, report, or metrics connector this workspace has.`,
+          `Use the most recent complete period (yesterday, or the last business day). Render quantitative comparisons as bar fills with a direction glyph and the delta, for example "Grocery 162 ██████████ ▼ -7%".`,
+          `Name the strongest positive and the clearest pain. If the source cannot be read, write "Pulse: unavailable" with the reason; never imply data you did not pull.`,
+        ].join(' '),
+      }
+    }
+    case 'skill': {
+      const name = str(o, 'name')
+      if (!name) return null
+      const slash = name.startsWith('/') ? name : `/${name}`
+      return {
+        label: `SKILL ${slash}`,
+        body: [
+          `Run this workspace's ${slash} skill exactly as it is defined (look under .claude/skills, .agents/skills, .claude/commands, and ~/.codex/prompts) and use its output for this section.`,
+          `Do not summarise it away; it was written for this purpose. If the skill does not exist, write one line saying so and continue with the other sections.`,
+        ].join(' '),
+      }
+    }
+    case 'custom': {
+      const instruction = str(o, 'instruction')
+      if (!instruction) return null
+      return { label: 'ALSO', body: instruction }
+    }
+  }
+}
+
+const KNOWN_IDS = new Set<MorningBriefSourceId>(MORNING_BRIEF_SOURCES.map(spec => spec.id))
+
+/** Compose the brief prompt. Enabled sources become numbered sections in the
+ * user's order; a section whose source has nothing to say is skipped. */
+export function composeMorningBriefPrompt(input: MorningBriefPromptInput): string {
+  const { config, day, ownerName, trigger } = input
+  const slotMinutes = parseTime(config.time)
+  const slot = `${String(Math.floor(slotMinutes / 60)).padStart(2, '0')}:${String(slotMinutes % 60).padStart(2, '0')}`
+  const sections = config.sources
+    .filter(source => source.enabled && KNOWN_IDS.has(source.id))
+    .map(source => sectionInstruction(source, day))
+    .filter((section): section is { label: string; body: string } => section !== null)
+
+  const skillOnly = sections.length === 1 && sections[0].label.startsWith('SKILL ')
+
+  const lines: string[] = []
+  lines.push(`Morning brief for ${ownerName || 'the wearer'}. ${describeDay(day)}, ${slot} ${config.timezone}.${trigger === 'manual' ? ' Requested now rather than on the schedule.' : ''}`)
+  lines.push('')
+  lines.push(
+    'This is the start-of-day brief that waits in the COS Glasses inbox before the wearer opens it. Nobody is watching this run: do not ask questions, do not pause for confirmation, and do not stop early. ' +
+    'It is read-only. Do not send messages or email, create or change calendar events, edit tasks, or write files other than any journal or log a skill you run is already designed to keep.',
+  )
+  lines.push('')
+  lines.push(
+    'Evidence discipline: every line must come from something you actually read in this workspace or through its connectors. ' +
+    'When a source cannot be read, give that section one line, "<Section>: unavailable (reason)", and move on. Never invent a meeting, a message, a number, or a name. ' +
+    'An aside is not a finding; include only items with a hard edge (a decision, a date, a dollar figure, an owner).',
+  )
+  lines.push('')
+
+  if (sections.length === 0) {
+    lines.push('No sections are enabled. Reply with exactly one line: "Morning brief: no sources selected. Choose sources in COS Control or the companion app."')
+  } else if (skillOnly) {
+    lines.push('Content:')
+    lines.push(`1. ${sections[0].label}. ${sections[0].body}`)
+  } else {
+    lines.push('Sections, in this order, each opened by its label on its own line:')
+    sections.forEach((section, index) => {
+      lines.push(`${index + 1}. ${section.label}. ${section.body}`)
+    })
+  }
+  lines.push('')
+
+  if (config.closingInstruction) {
+    lines.push(`Also: ${config.closingInstruction}`)
+    lines.push('')
+  }
+
+  lines.push(
+    'Format for the glasses: plain text only. No markdown headings, tables, or bullet symbols; a section is its label on one line followed by short lines. ' +
+    'Keep every line under 60 characters where you can, because the lens is 576 pixels wide and wraps silently. Keep the whole brief under about 60 lines; ' +
+    (skillOnly
+      ? 'if the skill\'s own output format is longer, keep it intact rather than trimming it.'
+      : 'trim from the bottom of each section, not from the top.'),
+  )
+  lines.push(
+    'End with one line beginning "Order your energy:" naming the single posture for the day, grounded in the sections above.',
+  )
+  lines.push('Do not say "here is" or "I found". Do not add a preamble or a sign-off.')
+
+  const prompt = lines.join('\n')
+  return prompt.length > MORNING_BRIEF_PROMPT_MAX_CHARS
+    ? `${prompt.slice(0, MORNING_BRIEF_PROMPT_MAX_CHARS - 1)}…`
+    : prompt
+}

package/server/lib/morning-brief-runtime.ts

@@ -0,0 +1,58 @@
+// Morning brief — the one production scheduler, wired to the real coordinator.
+//
+// Mirrors query-job-runtime.ts: the module owns the singleton so the router,
+// health, and index.ts all see the same instance, and tests construct their
+// own MorningBriefScheduler with fake deps instead of importing this file.
+
+import { getActiveSessions, createSession } from './conversation.js'
+import { currentMessageEra, exchangeBelongsToEra } from './message-era.js'
+import { maxGlobalMsgNumInDir } from '../routes/message-ref.js'
+import { dataPath } from './data-dir.js'
+import { getOwnerName } from './profile.js'
+import { durableQueryJobsEnabled } from './query-job-feature.js'
+import { queryJobCoordinator } from './query-job-runtime.js'
+import { maintenanceAdmissionsOpen } from './maintenance-lifecycle.js'
+import { morningBriefPaths } from './morning-brief-config.js'
+import { MorningBriefScheduler } from './morning-brief-scheduler.js'
+
+/** Highest stamped message number in the active era: live sessions plus the
+ * day archives. The same arithmetic /api/message-counter serves the phone. */
+export function currentMessageMax(): number {
+  const era = currentMessageEra()
+  let liveMax = 0
+  for (const session of getActiveSessions()) {
+    for (const exchange of (session as { exchanges?: Array<{ globalMsgNum?: unknown; messageEra?: unknown }> }).exchanges ?? []) {
+      if (!exchangeBelongsToEra(exchange, era)) continue
+      if (typeof exchange?.globalMsgNum === 'number' && exchange.globalMsgNum > liveMax) liveMax = exchange.globalMsgNum
+    }
+  }
+  return Math.max(liveMax, maxGlobalMsgNumInDir(dataPath('archive'), era))
+}
+
+let scheduler: MorningBriefScheduler | null = null
+
+export function getMorningBriefScheduler(): MorningBriefScheduler {
+  if (!scheduler) {
+    scheduler = new MorningBriefScheduler({
+      paths: morningBriefPaths(),
+      submit: raw => queryJobCoordinator.submit(raw),
+      findByClientGeneration: (clientJobId, generation) => queryJobCoordinator.getByClientGeneration(clientJobId, generation),
+      getSnapshot: jobId => queryJobCoordinator.getSnapshot(jobId),
+      createSession,
+      currentMessageEra,
+      currentMessageMax,
+      ownerName: getOwnerName,
+      durableJobsEnabled: durableQueryJobsEnabled,
+      admissionsOpen: maintenanceAdmissionsOpen,
+    })
+  }
+  return scheduler
+}
+
+export function startMorningBriefScheduler(): void {
+  getMorningBriefScheduler().start()
+}
+
+export function stopMorningBriefScheduler(): void {
+  scheduler?.stop()
+}

package/server/lib/morning-brief-schedule.ts

@@ -0,0 +1,158 @@
+// Morning brief — pure schedule arithmetic in the user's zone.
+//
+// No dependency: Node's Intl is enough to read a wall clock in an IANA zone,
+// and the two operations the scheduler needs — "what local day and minute is
+// it now" and "when is HH:MM on day D as an instant" — are both derivable from
+// it. Kept free of timers and I/O so the fire/no-fire decision is a table of
+// inputs a test can enumerate: the Mac asleep through the slot, a weekend, a
+// zone change, a DST morning, a second tick in the same minute.
+
+import type { MorningBriefConfig, MorningBriefRun } from './morning-brief-config.js'
+import { MORNING_BRIEF_LIMITS } from './morning-brief-config.js'
+
+export interface LocalClock {
+  /** YYYY-MM-DD in the zone. */
+  day: string
+  /** Minutes since local midnight, 0..1439. */
+  minutes: number
+  /** 0 = Sunday … 6 = Saturday, in the zone. */
+  weekday: number
+  /** HH:MM in the zone. */
+  time: string
+}
+
+const WEEKDAY_INDEX: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 }
+const formatterCache = new Map<string, Intl.DateTimeFormat>()
+
+function formatter(timezone: string): Intl.DateTimeFormat {
+  let cached = formatterCache.get(timezone)
+  if (!cached) {
+    cached = new Intl.DateTimeFormat('en-US', {
+      timeZone: timezone,
+      hourCycle: 'h23',
+      weekday: 'short',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+    })
+    formatterCache.set(timezone, cached)
+  }
+  return cached
+}
+
+/** Read the wall clock at `nowMs` in `timezone`. */
+export function localClock(nowMs: number, timezone: string): LocalClock {
+  const parts = formatter(timezone).formatToParts(new Date(nowMs))
+  const get = (type: Intl.DateTimeFormatPartTypes) => parts.find(part => part.type === type)?.value ?? ''
+  // `hourCycle: 'h23'` is honoured by modern ICU, but "24" has been observed
+  // from older builds at midnight. Normalise defensively.
+  const hour = Number(get('hour')) % 24
+  const minute = Number(get('minute'))
+  return {
+    day: `${get('year')}-${get('month')}-${get('day')}`,
+    minutes: hour * 60 + minute,
+    weekday: WEEKDAY_INDEX[get('weekday')] ?? new Date(nowMs).getUTCDay(),
+    time: `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`,
+  }
+}
+
+export function parseTime(time: string): number {
+  const [h, m] = time.split(':').map(Number)
+  return h * 60 + m
+}
+
+/** Shift a YYYY-MM-DD key by whole days (calendar arithmetic, zone-agnostic). */
+export function shiftDay(day: string, delta: number): string {
+  const [y, m, d] = day.split('-').map(Number)
+  const date = new Date(Date.UTC(y, m - 1, d + delta))
+  return `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}-${String(date.getUTCDate()).padStart(2, '0')}`
+}
+
+/**
+ * The instant at which `day` reaches `minutes` past midnight in `timezone`.
+ * Two-pass offset correction: read the zone's wall clock at a UTC guess, apply
+ * the difference, and re-check once so a DST transition between the guess and
+ * the target lands on the right side. On a non-existent local time (spring
+ * forward) this returns the first instant after the gap.
+ */
+export function zonedInstant(day: string, minutes: number, timezone: string): number {
+  const [y, m, d] = day.split('-').map(Number)
+  let guess = Date.UTC(y, m - 1, d, Math.floor(minutes / 60), minutes % 60)
+  for (let pass = 0; pass < 2; pass++) {
+    const clock = localClock(guess, timezone)
+    const dayDelta = daysBetween(clock.day, day)
+    const diffMinutes = dayDelta * 1440 + (minutes - clock.minutes)
+    if (diffMinutes === 0) break
+    guess += diffMinutes * 60_000
+  }
+  return guess
+}
+
+function daysBetween(fromDay: string, toDay: string): number {
+  const [fy, fm, fd] = fromDay.split('-').map(Number)
+  const [ty, tm, td] = toDay.split('-').map(Number)
+  return Math.round((Date.UTC(ty, tm - 1, td) - Date.UTC(fy, fm - 1, fd)) / 86_400_000)
+}
+
+/** ISO instant of the next scheduled fire at or after `nowMs`, or null when
+ * the brief is disabled or no weekday is selected. */
+export function nextScheduledFire(config: MorningBriefConfig, nowMs: number): string | null {
+  if (!config.enabled || config.days.length === 0) return null
+  const target = parseTime(config.time)
+  const clock = localClock(nowMs, config.timezone)
+  for (let offset = 0; offset <= 7; offset++) {
+    const day = shiftDay(clock.day, offset)
+    const instant = zonedInstant(day, target, config.timezone)
+    const weekday = localClock(instant, config.timezone).weekday
+    if (!config.days.includes(weekday)) continue
+    if (instant >= nowMs) return new Date(instant).toISOString()
+  }
+  return null
+}
+
+export type FireDecision =
+  | { fire: true; day: string; attempt: number; resume?: MorningBriefRun }
+  | { fire: false; reason: 'disabled' | 'not_a_brief_day' | 'before_slot' | 'window_closed' | 'already_fired' | 'in_flight' | 'attempts_exhausted' | 'backoff' }
+
+/**
+ * Should the scheduled brief fire on this tick? The ledger is the memory: one
+ * completed submission per local day, bounded retries for a submission that
+ * failed (coordinator shutting down, store degraded), and a row that has no
+ * job id and no error is a crash between ledger write and admission — resumed
+ * by client identity rather than re-run.
+ */
+export function decideScheduledFire(
+  config: MorningBriefConfig,
+  runs: readonly MorningBriefRun[],
+  nowMs: number,
+): FireDecision {
+  if (!config.enabled) return { fire: false, reason: 'disabled' }
+  const clock = localClock(nowMs, config.timezone)
+  if (!config.days.includes(clock.weekday)) return { fire: false, reason: 'not_a_brief_day' }
+  const target = parseTime(config.time)
+  if (clock.minutes < target) return { fire: false, reason: 'before_slot' }
+  if (clock.minutes - target > config.catchUpMinutes) return { fire: false, reason: 'window_closed' }
+
+  const today = runs.filter(run => run.day === clock.day && run.trigger === 'scheduled')
+  const accepted = today.find(run => run.jobId)
+  if (accepted) return { fire: false, reason: 'already_fired' }
+  const last = today.at(-1)
+  if (!last) return { fire: true, day: clock.day, attempt: 1 }
+  const lastAt = Date.parse(last.firedAt)
+  if (!last.submitError) {
+    // Ledger row exists, no job id, no error: submission never reported back.
+    // Give it a moment (the write happens just before submit), then resume by
+    // identity so a lost admission is adopted instead of duplicated.
+    if (Number.isFinite(lastAt) && nowMs - lastAt < MORNING_BRIEF_LIMITS.attemptSpacingMs) {
+      return { fire: false, reason: 'in_flight' }
+    }
+    return { fire: true, day: clock.day, attempt: last.attempt, resume: last }
+  }
+  if (last.attempt >= MORNING_BRIEF_LIMITS.scheduledAttemptsPerDay) return { fire: false, reason: 'attempts_exhausted' }
+  if (Number.isFinite(lastAt) && nowMs - lastAt < MORNING_BRIEF_LIMITS.attemptSpacingMs) {
+    return { fire: false, reason: 'backoff' }
+  }
+  return { fire: true, day: clock.day, attempt: last.attempt + 1 }
+}