@gotcos/glasses-server 6.98.1 → 6.99.12

package/server/lib/drop-p2-settings.ts

@@ -0,0 +1,174 @@
+/**
+ * Drop it P2 settings (Miles, 2026-11-04 23:39): how COS reaches out, so it can be tuned and steered.
+ *
+ * Every value here is read by the code that does the thing (ping-budget, ping-engine, ping-sources, drop-when,
+ * reminder-scheduler, drop-p2-runtime), and each has a test proving it changes behaviour. Defaults are the decided
+ * values (plan section 10), so a Mac with no settings file behaves exactly as 6.99.11 was built.
+ *
+ * Stored beside Drop it's switch, in its own file (`data/drop-p2-settings.json`, 0600, atomic), so the P1 settings
+ * file and its `{ enabled }` route stay as COS Control 0.5.371 reads them. Validation clamps a number into range and
+ * replaces a value it cannot read with the default; it never refuses a whole save for one bad field, but the PUT route
+ * refuses a body that is not an object or names an unknown section.
+ *
+ * Steer is words, not a model: "Ping me about" and "Leave alone" are each up to 300 characters, matched as whole
+ * words of 3 or more letters (canary 9: the ping path calls no model).
+ */
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import type { BudgetOptions, PingSource } from './ping-budget.js'
+
+export const P2_SETTINGS_PROTOCOL = 1
+export const P2_SETTINGS_FILE = () => dataPath('drop-p2-settings.json')
+
+/** The polled ping sources he can switch off one by one. Reminders and follow-ups have their own sections. */
+export const P2_PING_SOURCES = ['prep', 'agent', 'followups', 'stale', 'signals'] as const
+export type P2PingSource = typeof P2_PING_SOURCES[number]
+export const P2_FOLLOWUP_KINDS = ['card', 'handoff', 'session', 'thread'] as const
+export type P2FollowupKind = typeof P2_FOLLOWUP_KINDS[number]
+/** What may banner. `reminder` and `resolution` (follow-ups to his own drops) are on by default; the rest land silently. */
+export const P2_BANNER_KINDS = ['reminder', 'resolution', 'prep', 'agent', 'followups', 'stale', 'checkin'] as const
+
+export interface P2Settings {
+  pings: {
+    on: boolean
+    dailyCap: number
+    perSource: number
+    gapMinutes: number
+    quietStart: string
+    quietEnd: string
+    weekendsQuiet: boolean
+    firstBanner: string
+    sources: Record<P2PingSource, boolean>
+  }
+  followUps: { on: boolean; kinds: Record<P2FollowupKind, boolean> }
+  checkin: { on: boolean; weekday: number; time: string }
+  reminders: { defaultTime: string; snoozeMinutes: number; banners: boolean; lensPush: boolean }
+  banners: Record<(typeof P2_BANNER_KINDS)[number], boolean>
+  steer: { about: string; leaveAlone: string }
+}
+
+export const P2_LIMITS = {
+  dailyCap: [0, 20], perSource: [1, 10], gapMinutes: [0, 240], snoozeMinutes: [5, 24 * 60], steerChars: 300,
+} as const
+
+export const P2_DEFAULTS: P2Settings = {
+  pings: { on: true, dailyCap: 6, perSource: 2, gapMinutes: 45, quietStart: '18:00', quietEnd: '06:00', weekendsQuiet: true, firstBanner: '08:00',
+    sources: { prep: true, agent: true, followups: true, stale: true, signals: true } },
+  followUps: { on: true, kinds: { card: true, handoff: true, session: true, thread: true } },
+  checkin: { on: true, weekday: 1, time: '09:00' },
+  reminders: { defaultTime: '09:00', snoozeMinutes: 60, banners: true, lensPush: true },
+  banners: { reminder: true, resolution: true, prep: false, agent: false, followups: false, stale: false, checkin: false },
+  steer: { about: '', leaveAlone: '' },
+}
+
+const TIME = /^([01]\d|2[0-3]):([0-5]\d)$/
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+const bool = (v: unknown, d: boolean) => typeof v === 'boolean' ? v : d
+const int = (v: unknown, [lo, hi]: readonly [number, number], d: number) => typeof v === 'number' && Number.isFinite(v) ? Math.min(hi, Math.max(lo, Math.round(v))) : d
+const time = (v: unknown, d: string) => typeof v === 'string' && TIME.test(v) ? v : d
+const text = (v: unknown, d: string) => typeof v === 'string' ? v.replace(/[\x00-\x1f\x7f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, P2_LIMITS.steerChars) : d
+function flags<K extends string>(v: unknown, keys: readonly K[], d: Record<K, boolean>): Record<K, boolean> {
+  const out = { ...d }
+  if (isRecord(v)) for (const k of keys) out[k] = bool(v[k], d[k])
+  return out
+}
+
+/** Read any object as settings: unknown fields are dropped, numbers clamped, unreadable values left at `base`. */
+export function normalizeP2Settings(raw: unknown, base: P2Settings = P2_DEFAULTS): P2Settings {
+  const r = isRecord(raw) ? raw : {}
+  const p = isRecord(r.pings) ? r.pings : {}, f = isRecord(r.followUps) ? r.followUps : {}, c = isRecord(r.checkin) ? r.checkin : {}
+  const m = isRecord(r.reminders) ? r.reminders : {}, s = isRecord(r.steer) ? r.steer : {}
+  return {
+    pings: {
+      on: bool(p.on, base.pings.on),
+      dailyCap: int(p.dailyCap, P2_LIMITS.dailyCap, base.pings.dailyCap),
+      perSource: int(p.perSource, P2_LIMITS.perSource, base.pings.perSource),
+      gapMinutes: int(p.gapMinutes, P2_LIMITS.gapMinutes, base.pings.gapMinutes),
+      quietStart: time(p.quietStart, base.pings.quietStart),
+      quietEnd: time(p.quietEnd, base.pings.quietEnd),
+      weekendsQuiet: bool(p.weekendsQuiet, base.pings.weekendsQuiet),
+      firstBanner: time(p.firstBanner, base.pings.firstBanner),
+      sources: flags(p.sources, P2_PING_SOURCES, base.pings.sources),
+    },
+    followUps: { on: bool(f.on, base.followUps.on), kinds: flags(f.kinds, P2_FOLLOWUP_KINDS, base.followUps.kinds) },
+    checkin: { on: bool(c.on, base.checkin.on), weekday: int(c.weekday, [0, 6], base.checkin.weekday), time: time(c.time, base.checkin.time) },
+    reminders: {
+      defaultTime: time(m.defaultTime, base.reminders.defaultTime),
+      snoozeMinutes: int(m.snoozeMinutes, P2_LIMITS.snoozeMinutes, base.reminders.snoozeMinutes),
+      banners: bool(m.banners, base.reminders.banners),
+      lensPush: bool(m.lensPush, base.reminders.lensPush),
+    },
+    banners: flags(r.banners, P2_BANNER_KINDS, base.banners),
+    steer: { about: text(s.about, base.steer.about), leaveAlone: text(s.leaveAlone, base.steer.leaveAlone) },
+  }
+}
+
+/** Apply a partial PUT onto the current settings: only the fields it names change. */
+export function mergeP2Settings(current: P2Settings, patch: unknown): P2Settings {
+  return normalizeP2Settings(patch, current)
+}
+
+const minutes = (hhmm: string) => Number(hhmm.slice(0, 2)) * 60 + Number(hhmm.slice(3))
+/** The numbers the budget and quiet hours read, in the units they use. */
+export function budgetFrom(s: P2Settings): BudgetOptions {
+  return {
+    perWeekday: s.pings.dailyCap, perSource: s.pings.perSource, gapMs: s.pings.gapMinutes * 60_000,
+    quietStartMinutes: minutes(s.pings.quietStart), quietEndMinutes: minutes(s.pings.quietEnd),
+    weekendsQuiet: s.pings.weekendsQuiet, firstBannerMinutes: minutes(s.pings.firstBanner),
+  }
+}
+export const timeMinutes = minutes
+
+/** The kinds that may banner, as the budget reads them. Reminder banners also need the reminders switch. */
+export function bannerSourcesFrom(s: P2Settings): PingSource[] {
+  return P2_BANNER_KINDS.filter(k => s.banners[k] && (k !== 'reminder' || s.reminders.banners)) as PingSource[]
+}
+
+/** Whole words of 3 or more letters, lowercased, at most 40: what the steer boxes match. */
+export function steerWords(textValue: string): string[] {
+  const out = new Set<string>()
+  for (const w of textValue.normalize('NFKC').toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    if (w.length >= 3 && !STEER_STOP.has(w)) out.add(w)
+    if (out.size >= 40) break
+  }
+  return [...out]
+}
+const STEER_STOP = new Set('the and for with from about that this those these any all ping pings me my you your not dont leave alone please stuff things don won can'.split(' '))
+/** True when `line` contains any of `words` as a whole word. */
+export function matchesSteer(line: string, words: readonly string[]): boolean {
+  if (!words.length) return false
+  const have = new Set(line.normalize('NFKC').toLowerCase().split(/[^\p{L}\p{N}]+/u))
+  return words.some(w => have.has(w))
+}
+
+/** Read the settings file, or the defaults when it is missing, unsafe or unreadable. Never throws. */
+export function readP2Settings(file = P2_SETTINGS_FILE()): P2Settings {
+  try {
+    if (!existsSync(file)) return P2_DEFAULTS
+    const st = lstatSync(file)
+    if (!st.isFile() || st.isSymbolicLink() || st.size > 64 * 1024) return P2_DEFAULTS
+    const raw = JSON.parse(readFileSync(file, 'utf8'))
+    return normalizeP2Settings(isRecord(raw) && raw.v === P2_SETTINGS_PROTOCOL ? raw.settings : null)
+  } catch { return P2_DEFAULTS }
+}
+
+export function writeP2Settings(settings: P2Settings, file = P2_SETTINGS_FILE()): void {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+  durableAtomicWriteFileSync(file, JSON.stringify({ v: P2_SETTINGS_PROTOCOL, settings: normalizeP2Settings(settings) }, null, 2) + '\n')
+  try { chmodSync(file, 0o600) } catch { /* best effort: the folder is 0700 */ }
+}
+
+/** A cache so the engine's minute tick does not re-read the file each time; a write through this module clears it. */
+export function createP2SettingsReader(file = P2_SETTINGS_FILE(), ttlMs = 15_000, now: () => number = Date.now) {
+  let cached: { at: number; settings: P2Settings } | null = null
+  return {
+    read(): P2Settings {
+      if (cached && now() - cached.at < ttlMs) return cached.settings
+      cached = { at: now(), settings: readP2Settings(file) }
+      return cached.settings
+    },
+    write(next: P2Settings): P2Settings { writeP2Settings(next, file); cached = { at: now(), settings: normalizeP2Settings(next) }; return cached.settings },
+  }
+}

package/server/lib/drop-resolution.ts

@@ -0,0 +1,168 @@
+/**
+ * Drop it P2 (plan PLAN_drop_it_2026-11-04 section 4): the resolution loop. "Your Work item finished", once.
+ *
+ * Links are stable ids, never titles: a card is its domain plus workIdentity, a handoff is its journal receipt id,
+ * a session is provider:native, a thread its id. Detection runs two ways that must agree:
+ * - events from the server's own writes (a card moved through /api/work-board or /api/tasks), and
+ * - a 2-minute poll of the linked open cards and their handoff receipts, because the helper and other sessions
+ *   write tasks.md directly.
+ *
+ * Exactly once (canary 7): the key is `dropId:linkKind:linkId:state`, and the feed store's insert is idempotent on
+ * it under the store lock, written before any banner. A state seen by both the event and the poll, or again after a
+ * restart, finds the key and stops. A QA, Draft, QA bounce posts once.
+ *
+ * What posts: a card reaching QA or Complete, or archived; a handoff completed (with its report, 240 characters),
+ * failed or refused; a session follow-up that was replied to or failed; a thread resolved or gone stale. Other moves
+ * change only the drop's status in History. No model, no script; the words are templates over the link's label.
+ */
+import type { DropRecord, DropLink } from './drop-store.js'
+import { clip, PING_TEXT, type PingCandidate } from './ping-sources.js'
+
+/** Control's report clip (C WorkProgressTracker.swift:588). */
+export const RESOLUTION_REPORT_CHARS = 240
+export const RESOLUTION_POLL_MS = 2 * 60_000
+/** Drops older than this are not polled: a card that resolves after a quarter is not news about the drop. */
+export const RESOLUTION_WINDOW_DAYS = 90
+
+export type CardState = 'qa' | 'complete' | 'archived'
+export type HandoffState = 'completed' | 'failed' | 'refused'
+export type SessionState = 'replied' | 'failed'
+export type ThreadState = 'resolved' | 'stale'
+
+export interface CardSnapshot { workStage?: string; checked?: boolean }
+export interface HandoffSnapshot { id: string; status: string; result?: string | null }
+export interface ThreadSnapshot { is_resolved?: boolean; is_stale?: boolean }
+
+/** What a card's board row says, as a resolution state, or null for a move that only updates status silently. */
+export function cardState(row: CardSnapshot | null | undefined): CardState | null {
+  if (row === null) return 'archived'  // absent from the board: archived ([~]) or removed
+  if (!row) return null
+  if (row.checked === true || row.workStage === 'complete') return 'complete'
+  if (row.workStage === 'qa') return 'qa'
+  return null
+}
+export function handoffState(receipt: HandoffSnapshot | null | undefined): HandoffState | null {
+  const s = receipt?.status
+  return s === 'completed' || s === 'failed' || s === 'refused' ? s : null
+}
+export function threadState(t: ThreadSnapshot | null | undefined): ThreadState | null {
+  if (!t) return null
+  if (t.is_resolved === true) return 'resolved'
+  if (t.is_stale === true) return 'stale'
+  return null
+}
+
+/** The exactly-once key. */
+export const resolutionKey = (dropId: string, link: Pick<DropLink, 'kind' | 'id'>, state: string) => `${dropId}:${link.kind}:${link.id}:${state}`
+
+const OPEN_CARD = { id: 'open_card', label: 'Open card' }
+const OPEN_RESULT = { id: 'open_result', label: 'Open result' }
+const OPEN = { id: 'open', label: 'Open' }
+
+/** "Re: send Gina the JCK numbers": the one-line quote of the drop a follow-up answers (plan section 1). */
+export function quoteOf(drop: Pick<DropRecord, 'text'>): string {
+  return `Re: ${clip(drop.text, 80)}`
+}
+
+/** The follow-up for one link reaching one state. */
+export function resolutionCandidate(
+  drop: Pick<DropRecord, 'id' | 'text'>,
+  link: DropLink,
+  state: CardState | HandoffState | SessionState | ThreadState,
+  nowMs: number,
+  extra: { report?: string | null; handoffId?: string } = {},
+): PingCandidate {
+  const label = clip(link.label, PING_TEXT.title) || 'it'
+  const base = { source: 'resolution' as const, key: resolutionKey(drop.id, extra.handoffId ? { kind: 'handoff', id: extra.handoffId } : link, state), title: quoteOf(drop), createdAt: nowMs, threadId: drop.id }
+  const report = extra.report ? clip(extra.report, RESOLUTION_REPORT_CHARS) : ''
+  switch (state) {
+    case 'complete': return { ...base, line: `Done: ${label} moved to Complete.`, links: [link], actions: [OPEN_CARD] }
+    case 'qa': return { ...base, line: `${label} is ready for your review.`, links: [link], actions: [OPEN_CARD], needsReply: true }
+    case 'archived': return { ...base, line: `${label} was archived.`, links: [link], actions: [] }
+    case 'completed': return { ...base, line: report ? `Done: ${label}. ${report}` : `Done: ${label}.`, links: [link], actions: [OPEN_RESULT, OPEN_CARD] }
+    case 'refused': return { ...base, line: `The agent refused ${label}.${report ? ` ${report}` : ''}`, links: [link], actions: [OPEN_RESULT, OPEN_CARD], needsReply: true }
+    case 'failed': return link.kind === 'session'
+      ? { ...base, line: `${label} stopped before it replied.`, links: [link], actions: [OPEN_RESULT], needsReply: true }
+      : { ...base, line: `${label} failed.${report ? ` ${report}` : ''}`, links: [link], actions: [OPEN_RESULT, OPEN_CARD], needsReply: true }
+    case 'replied': return { ...base, line: `${label} replied.`, links: [link], actions: [OPEN_RESULT] }
+    case 'resolved': return { ...base, line: `The ${label} thread is resolved.`, links: [link], actions: [OPEN] }
+    case 'stale': return { ...base, line: `The ${label} thread went quiet.`, links: [link], actions: [OPEN] }
+  }
+}
+
+/** Drops whose links the poll follows: filed, not undone, inside the window, with a card, thread or held session. */
+export function followedDrops(drops: readonly DropRecord[], nowMs: number): DropRecord[] {
+  const cutoff = nowMs - RESOLUTION_WINDOW_DAYS * 86_400_000
+  return drops.filter(d => d.state !== 'undone' && Date.parse(d.createdAt) >= cutoff && d.links.some(l => l.kind === 'card' || l.kind === 'thread'))
+}
+
+export interface ResolutionSnapshot {
+  /** Board rows keyed `${domain}:${workIdentity}`. Absent means the board could not be read (nothing is inferred). */
+  cards?: ReadonlyMap<string, CardSnapshot>
+  /** Handoff receipts for a card, keyed `${domain}:${workIdentity}`, journal order. */
+  handoffs?: ReadonlyMap<string, readonly HandoffSnapshot[]>
+  /** Thread rows by id. Absent means the cache could not be read. */
+  threads?: ReadonlyMap<string, ThreadSnapshot>
+}
+
+/**
+ * The follow-ups a poll (or an event, as a one-card snapshot) finds. Pure: candidates out, and the ping engine posts
+ * each key at most once. A card missing from a board that WAS read counts as archived; an unread board says nothing.
+ */
+export function pollResolutions(drops: readonly DropRecord[], snap: ResolutionSnapshot, nowMs: number): PingCandidate[] {
+  const out: PingCandidate[] = []
+  for (const drop of followedDrops(drops, nowMs)) {
+    for (const link of drop.links) {
+      if (link.kind === 'card' && link.domain && snap.cards) {
+        const key = `${link.domain}:${link.id}`
+        const row = snap.cards.has(key) ? snap.cards.get(key)! : null
+        const state = cardState(row)
+        if (state) out.push(resolutionCandidate(drop, link, state, nowMs))
+        for (const receipt of snap.handoffs?.get(key) ?? []) {
+          const h = handoffState(receipt)
+          if (h) out.push(resolutionCandidate(drop, link, h, nowMs, { report: receipt.result ?? null, handoffId: receipt.id }))
+        }
+      } else if (link.kind === 'thread' && snap.threads) {
+        const state = threadState(snap.threads.get(link.id))
+        if (state) out.push(resolutionCandidate(drop, link, state, nowMs))
+      }
+    }
+  }
+  return out
+}
+
+/** An event from the server's own card write: the same rule as the poll, for the drops linked to that one card. */
+export function cardWriteResolutions(drops: readonly DropRecord[], domain: string, workIdentity: string, row: CardSnapshot | null, nowMs: number): PingCandidate[] {
+  const linked = drops.filter(d => d.links.some(l => l.kind === 'card' && l.domain === domain && l.id === workIdentity))
+  return pollResolutions(linked, { cards: new Map(row ? [[`${domain}:${workIdentity}`, row]] : []) }, nowMs)
+    .filter(c => !c.key.includes(':handoff:'))
+}
+
+/** A session hook event as a turn outcome: Stop is a reply; StopFailure and Interrupt stopped it. A subagent's never counts. */
+export function sessionTurnOutcome(event: string, child: boolean): SessionState | null {
+  if (child) return null
+  if (event === 'Stop') return 'replied'
+  if (event === 'StopFailure' || event === 'Interrupt') return 'failed'
+  return null
+}
+
+/** A held drop names its session as `provider:native` or the bare native id; the hooks report the native id. */
+export function sameHeldSession(held: string, hookSessionId: string): boolean {
+  const a = held.toLowerCase(), b = hookSessionId.toLowerCase()
+  return a === b || a.endsWith(`:${b}`)
+}
+
+/**
+ * The turn after Send to session ended (SessionSignalStore): replied or failed, for the drops held for it. Only a turn
+ * that ended after the drop was sent counts, so the end of the turn already running at Send is never its answer.
+ */
+export function sessionTurnResolutions(drops: readonly DropRecord[], sessionId: string, outcome: SessionState, nowMs: number, endedAtMs = nowMs): PingCandidate[] {
+  const out: PingCandidate[] = []
+  for (const d of drops) {
+    if (d.state === 'undone' || d.dest !== 'session' || !d.hold?.sentAt || !sameHeldSession(d.hold.sessionId, sessionId)) continue
+    if (!(Date.parse(d.hold.sentAt) < endedAtMs)) continue
+    const link: DropLink = d.links.find(l => l.kind === 'session' && sameHeldSession(l.id, sessionId)) ?? { kind: 'session', id: d.hold.sessionId, label: d.hold.label }
+    out.push(resolutionCandidate(d, link, outcome, nowMs))
+  }
+  return out
+}