@huynle/hub 0.7.4 → 0.8.0

package/src/central/concierge/watchlist.ts

@@ -0,0 +1,273 @@
+// CON-01 watchlist (contract: docs/plans/2026-11-01-concierge-contracts.md, "Watchlist (CON-01)"): which of a user's
+// sessions the Concierge watches. Pure parts only: the resolution (resolveWatchlist) over facts gathered elsewhere
+// (watchlist-routes.ts), the default config and the validation of an update. Nothing here reads a store or a spoke.
+//
+// Resolution: root sessions only (subagents roll up into their root: state, blockers, Decisions, activity, and the
+// IDs in pins, explicit sessions and mutes). Included by reason:
+//   active          the tree is working, blocked or in error, has an open blocker or an open Decision about it, or was
+//                   active within activeWithinHours (autoActive)
+//   pinned          viewPrefs.pinnedSessions (usePins)
+//   pinned_project  viewPrefs.pinnedWorkspaces: `herdr:<id>` = the terminal workspace, else a folder matched as a
+//                   project/directory prefix on path boundaries (inProjects) (usePins)
+//   explicit        config.sessions
+//   project         config.projects (inProjects)
+//   label           a config.labels filter whose pairs all equal the launch's labels
+// minus muted / mutedProjects (an offline session without a known directory: by its project slug), archived, deleted or
+// gone sessions (CON-12: its machine is connected but no longer reports it) and every hidden (Concierge) session. Ordered by priority
+// (error, blocked, open Decision, working, then most recent activity, then ID) and cut at WATCHLIST_LIMITS.entries.
+// Notification mutes (store mutedSessions) are not inherited: they silence pushes, they do not mean "don't track".
+import { WATCHLIST_DEFAULTS, WATCHLIST_LIMITS, type WatchlistConfig, type WatchlistEntry, type WatchReason } from "../../../packages/protocol/src/concierge"
+import { isHubSessionID } from "../../../packages/protocol/src/harness-events"
+import { AgentError } from "../agent/errors"
+import { LABEL_KEY_MAX, LABEL_VALUE_MAX, LABELS_MAX } from "../agent/launch-spec"
+import { canonicalProject, inProjects } from "../agent/policy"
+import { slugify } from "../agent/names"
+import path from "node:path"
+
+const HOUR_MS = 3_600_000
+
+/** One session of the user (root or subagent) as the resolution sees it. */
+export interface WatchFact {
+  readonly sessionID: string
+  readonly parentID?: string
+  /** The session's own state (idle, working, blocked, error, offline, …). */
+  readonly state?: string
+  /** Open blockers (permissions, questions) of this session. */
+  readonly blockers: number
+  readonly directory?: string
+  /** The project (workspace) root directory, when it differs from the directory. */
+  readonly project?: string
+  /**
+   * The directory's project slug (AgentSession.project), known offline too: when no directory is known, mutedProjects
+   * match on it (a basename slug, so it may over-mute; it never includes anything).
+   */
+  readonly projectSlug?: string
+  /** The Herdr workspace it is open in. */
+  readonly herdrWorkspace?: string
+  readonly archived?: boolean
+  readonly deleted?: boolean
+  /**
+   * (CON-12) Gone: its machine is connected and no longer reports it (deleted or closed there; the console no longer
+   * lists it). A session of an offline machine is only offline (it may come back) and stays watchable.
+   */
+  readonly gone?: boolean
+  readonly lastActiveAt?: number
+  /** Labels of the launch that started it. */
+  readonly labels?: Readonly<Record<string, string>>
+}
+
+export interface WatchFacts {
+  readonly sessions: readonly WatchFact[]
+  /** The console's pins (viewPrefs.pinnedSessions / pinnedWorkspaces). */
+  readonly pins: { readonly sessions: readonly string[]; readonly workspaces: readonly string[] }
+  /** Sessions an open Decision is about (or was asked by). */
+  readonly decisions: readonly string[]
+  /** The Concierge's own sessions (current and previous): never watched. */
+  readonly hidden: readonly string[]
+  readonly now: number
+}
+
+export interface ResolvedWatchlist {
+  readonly entries: WatchlistEntry[]
+  readonly truncated: boolean
+}
+
+export function defaultWatchlist(): WatchlistConfig {
+  return { ...WATCHLIST_DEFAULTS, sessions: [], projects: [], labels: [], muted: [], mutedProjects: [], revision: 0 }
+}
+
+const REASON_ORDER: readonly WatchReason[] = ["active", "pinned", "pinned_project", "explicit", "project", "label"]
+
+interface Tree {
+  readonly root: WatchFact
+  error: boolean
+  blocked: boolean
+  decision: boolean
+  working: boolean
+  lastActiveAt?: number
+}
+
+/** The root of each session: parents followed while known (a cycle stops at the first repeat). */
+export function rootsOf(sessions: readonly WatchFact[]): Map<string, string> {
+  const byID = new Map(sessions.map((s) => [s.sessionID, s]))
+  const roots = new Map<string, string>()
+  for (const s of sessions) {
+    const seen = new Set<string>([s.sessionID])
+    let current = s
+    while (current.parentID !== undefined) {
+      const parent = byID.get(current.parentID)
+      if (!parent || seen.has(parent.sessionID)) break
+      seen.add(parent.sessionID)
+      current = parent
+    }
+    roots.set(s.sessionID, current.sessionID)
+  }
+  return roots
+}
+
+const dirsOf = (s: WatchFact): string[] => [s.project, s.directory].filter((d): d is string => typeof d === "string" && d.length > 0)
+const inAny = (s: WatchFact, projects: readonly string[]) => projects.length > 0 && dirsOf(s).some((dir) => inProjects(dir, projects))
+
+/** The project slug of a directory, as the directory derives it (slug of the folder name, else lowercased). */
+const slugOf = (dir: string) => {
+  const name = path.posix.basename(dir)
+  return name ? (slugify(name) ?? name.toLowerCase()) : undefined
+}
+
+/** Muted by project: a known directory decides; without one (offline), the project slug matches a muted folder's. */
+const inMutedProject = (s: WatchFact, muted: readonly string[]) => {
+  if (dirsOf(s).length > 0) return inAny(s, muted)
+  return s.projectSlug !== undefined && muted.some((dir) => slugOf(dir) === s.projectSlug)
+}
+
+function inPinnedWorkspace(s: WatchFact, workspaces: readonly string[]): boolean {
+  const folders: string[] = []
+  for (const key of workspaces) {
+    if (key.startsWith("herdr:")) {
+      if (s.herdrWorkspace !== undefined && key.slice("herdr:".length) === s.herdrWorkspace) return true
+    } else folders.push(key)
+  }
+  return inAny(s, folders)
+}
+
+const labelsMatch = (labels: Readonly<Record<string, string>> | undefined, filter: Readonly<Record<string, string>>) => {
+  const pairs = Object.entries(filter)
+  return labels !== undefined && pairs.length > 0 && pairs.every(([k, v]) => Object.hasOwn(labels, k) && labels[k] === v)
+}
+
+const rank = (t: Tree) => (t.error ? 0 : t.blocked ? 1 : t.decision ? 2 : t.working ? 3 : 4)
+
+export function resolveWatchlist(config: WatchlistConfig, facts: WatchFacts): ResolvedWatchlist {
+  const roots = rootsOf(facts.sessions)
+  const rootID = (id: string) => roots.get(id) ?? id
+  const decisions = new Set(facts.decisions)
+  const trees = new Map<string, Tree>()
+  const byID = new Map(facts.sessions.map((s) => [s.sessionID, s]))
+  for (const s of facts.sessions) {
+    const id = rootID(s.sessionID)
+    let tree = trees.get(id)
+    if (!tree) trees.set(id, (tree = { root: byID.get(id)!, error: false, blocked: false, decision: false, working: false }))
+    if (s.state === "error") tree.error = true
+    if (s.state === "blocked" || s.blockers > 0) tree.blocked = true
+    if (s.state === "working") tree.working = true
+    if (decisions.has(s.sessionID)) tree.decision = true
+    if (s.lastActiveAt !== undefined && (tree.lastActiveAt === undefined || s.lastActiveAt > tree.lastActiveAt)) tree.lastActiveAt = s.lastActiveAt
+  }
+  const rootSet = (ids: readonly string[]) => new Set(ids.map(rootID))
+  const hidden = rootSet(facts.hidden)
+  const muted = rootSet(config.muted)
+  const explicit = rootSet(config.sessions)
+  const pinned = config.usePins ? rootSet(facts.pins.sessions) : new Set<string>()
+  const since = facts.now - config.activeWithinHours * HOUR_MS
+
+  const out: { tree: Tree; entry: WatchlistEntry }[] = []
+  for (const [id, tree] of trees) {
+    const root = tree.root
+    if (root.archived || root.deleted || root.gone || hidden.has(id) || muted.has(id) || inMutedProject(root, config.mutedProjects)) continue
+    const reasons = new Set<WatchReason>()
+    const recent = tree.lastActiveAt !== undefined && tree.lastActiveAt >= since
+    if (config.autoActive && (tree.error || tree.blocked || tree.decision || tree.working || recent)) reasons.add("active")
+    if (pinned.has(id)) reasons.add("pinned")
+    if (config.usePins && inPinnedWorkspace(root, facts.pins.workspaces)) reasons.add("pinned_project")
+    if (explicit.has(id)) reasons.add("explicit")
+    if (inAny(root, config.projects)) reasons.add("project")
+    if (config.labels.some((filter) => labelsMatch(root.labels, filter))) reasons.add("label")
+    if (reasons.size === 0) continue
+    out.push({
+      tree,
+      entry: { sessionID: id, reasons: REASON_ORDER.filter((r) => reasons.has(r)), ...(tree.lastActiveAt !== undefined ? { lastActiveAt: tree.lastActiveAt } : {}) },
+    })
+  }
+  out.sort((a, b) => rank(a.tree) - rank(b.tree) || (b.tree.lastActiveAt ?? -1) - (a.tree.lastActiveAt ?? -1) || (a.entry.sessionID < b.entry.sessionID ? -1 : a.entry.sessionID > b.entry.sessionID ? 1 : 0))
+  return { entries: out.slice(0, WATCHLIST_LIMITS.entries).map((o) => o.entry), truncated: out.length > WATCHLIST_LIMITS.entries }
+}
+
+// ---- Update validation ----------------------------------------------------------------------------------------
+
+const FIELDS = new Set(["autoActive", "activeWithinHours", "usePins", "sessions", "projects", "labels", "muted", "mutedProjects", "revision", "expectedRevision"])
+const LABEL_KEY = /^[A-Za-z0-9](?:[A-Za-z0-9._/-]*[A-Za-z0-9])?$/
+/** C0 (tab and newline included), DEL, C1, Arabic letter mark, zero-width and bidi marks, separators, embeddings and overrides, word joiner, invisible operators, bidi isolates, BOM. */
+const UNSAFE = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/
+
+const invalid = (message: string) => new AgentError("invalid", message)
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const isRevision = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0
+
+function boolField(value: unknown, name: string): boolean {
+  if (typeof value !== "boolean") throw invalid(`${name} is true or false`)
+  return value
+}
+
+function stringList(value: unknown, name: string): string[] {
+  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) throw invalid(`${name} is a list of strings`)
+  return value
+}
+
+function capped<T>(list: T[], max: number, name: string): T[] {
+  if (list.length > max) throw invalid(`${name} has at most ${max} entries`)
+  return list
+}
+
+function sessionList(value: unknown, name: string, max: number): string[] {
+  const list = stringList(value, name)
+  for (const id of list) if (!isHubSessionID(id)) throw invalid(`${name}: ${String(id).slice(0, 40)} is not a session ID (ses_…)`)
+  return capped([...new Set(list)], max, name)
+}
+
+function projectList(value: unknown, name: string): string[] {
+  const out: string[] = []
+  for (const dir of stringList(value, name)) {
+    if (UNSAFE.test(dir)) throw invalid(`${name}: a directory has control, bidi or zero-width characters`)
+    const canonical = canonicalProject(dir)
+    if (canonical === undefined) throw invalid(`${name}: ${dir.slice(0, 80)} is not an absolute project directory`)
+    out.push(canonical)
+  }
+  return capped([...new Set(out)], WATCHLIST_LIMITS.projects, name)
+}
+
+function labelFilters(value: unknown): Record<string, string>[] {
+  if (!Array.isArray(value)) throw invalid("labels is a list of {key: value} filters")
+  capped(value, WATCHLIST_LIMITS.labels, "labels")
+  return value.map((filter, i) => {
+    if (!isObject(filter)) throw invalid(`labels[${i}] is a {key: value} filter`)
+    const pairs = Object.entries(filter)
+    if (pairs.length === 0 || pairs.length > LABELS_MAX) throw invalid(`labels[${i}] has 1–${LABELS_MAX} pairs`)
+    const out: Record<string, string> = {}
+    for (const [key, text] of pairs) {
+      if (UNSAFE.test(key)) throw invalid(`labels[${i}]: a key has control, bidi or zero-width characters`)
+      if (key.length > LABEL_KEY_MAX || !LABEL_KEY.test(key)) throw invalid(`labels[${i}]: ${key.slice(0, LABEL_KEY_MAX)} is not a label key (letters, digits, . _ / -; up to ${LABEL_KEY_MAX})`)
+      if (typeof text !== "string" || text.length > LABEL_VALUE_MAX || UNSAFE.test(text)) throw invalid(`labels[${i}].${key} is a string of up to ${LABEL_VALUE_MAX} characters`)
+      out[key] = text
+    }
+    return out
+  })
+}
+
+/**
+ * The config a PUT body asks for: any subset of the config fields plus the required expectedRevision (the
+ * `revision` read earlier may be echoed back, but must agree). Unknown fields, wrong types and caps are 400 invalid;
+ * a stale expectedRevision is 409 conflict {currentRevision}. The answer keeps `current.revision` (the store bumps it).
+ */
+export function parseWatchlistUpdate(body: unknown, current: WatchlistConfig): WatchlistConfig {
+  if (!isObject(body)) throw invalid("The body is a JSON object: watchlist fields and expectedRevision")
+  const unknown = Object.keys(body).find((k) => !FIELDS.has(k))
+  if (unknown !== undefined) throw invalid(`Unknown field ${unknown.slice(0, 40)}`)
+  const expected = body.expectedRevision
+  if (!isRevision(expected)) throw invalid("expectedRevision (the revision you read) is required")
+  if (body.revision !== undefined && body.revision !== expected) throw invalid("revision and expectedRevision disagree: send the revision you read as expectedRevision")
+  const next: { -readonly [K in keyof WatchlistConfig]: WatchlistConfig[K] } = { ...current }
+  if (body.autoActive !== undefined) next.autoActive = boolField(body.autoActive, "autoActive")
+  if (body.usePins !== undefined) next.usePins = boolField(body.usePins, "usePins")
+  if (body.activeWithinHours !== undefined) {
+    const hours = body.activeWithinHours
+    if (typeof hours !== "number" || !Number.isInteger(hours) || hours < 1 || hours > 24) throw invalid("activeWithinHours is a whole number of hours, 1–24")
+    next.activeWithinHours = hours
+  }
+  if (body.sessions !== undefined) next.sessions = sessionList(body.sessions, "sessions", WATCHLIST_LIMITS.sessions)
+  if (body.muted !== undefined) next.muted = sessionList(body.muted, "muted", WATCHLIST_LIMITS.muted)
+  if (body.projects !== undefined) next.projects = projectList(body.projects, "projects")
+  if (body.mutedProjects !== undefined) next.mutedProjects = projectList(body.mutedProjects, "mutedProjects")
+  if (body.labels !== undefined) next.labels = labelFilters(body.labels)
+  if (expected !== current.revision) throw new AgentError("conflict", `The watchlist changed since you read it (revision ${current.revision} now)`, { hint: "Read it again and retry", extra: { currentRevision: current.revision } })
+  return next
+}

package/src/central/config.ts

@@ -81,6 +81,8 @@ export interface ClusterConfig {
   readonly databaseURL: string
   /** redis://, rediss://, valkey:// or valkeys:// (non-enumerable). */
   readonly valkeyURL: string
+  /** HUB_DATABASE_STATEMENT_TIMEOUT_MS: Postgres statement_timeout in ms, 0 off (unset: the stores' 30 s default). */
+  readonly statementTimeoutMs?: number
 }
 
 /** hub.json `cluster` (env HUB_DATABASE_URL / HUB_VALKEY_URL win). */
@@ -433,7 +435,11 @@ function clusterConfig(env: Env, auth: AuthConfig, file: HubCluster = {}): Clust
   if (!POD_ID.test(podID)) {
     throw new Error(`HUB_POD_ID must be 1-128 letters, digits, '.', '_' or '-' (starting with a letter or digit), got ${JSON.stringify(podID)}`)
   }
-  const cluster = { podID }
+  const rawTimeout = env.HUB_DATABASE_STATEMENT_TIMEOUT_MS?.trim()
+  if (rawTimeout && !/^\d{1,9}$/.test(rawTimeout)) {
+    throw new Error(`HUB_DATABASE_STATEMENT_TIMEOUT_MS must be a whole number of milliseconds (0 turns it off), got ${JSON.stringify(rawTimeout)}`)
+  }
+  const cluster = { podID, ...(rawTimeout ? { statementTimeoutMs: Number(rawTimeout) } : {}) }
   // Getters: printed as nothing, skipped by JSON.stringify.
   Object.defineProperty(cluster, "databaseURL", { get: () => databaseURL, enumerable: false })
   Object.defineProperty(cluster, "valkeyURL", { get: () => valkeyURL, enumerable: false })