@huynle/hub 0.7.4 → 0.8.1

package/src/central/concierge/settings.ts

@@ -0,0 +1,217 @@
+// CON-04 Concierge settings (contract "Concierge service: settings, launch, supervise, hide, context"): one record
+// per user (collection `concierge`, key `settings`), edited only by the user (Settings → Concierge). A partial update
+// names `expectedRevision` (409 conflict {currentRevision} on a mismatch); unknown and read-only fields (enabled,
+// grantID, revision, updatedAt) are 400 invalid: enabling goes through POST /concierge/enable, the grant ID is the
+// hub's. `where: "hosted"` is reserved for C2 (422 unsupported {feature: "conciergeHosted"}). The grant spec becomes
+// a real grant held by @@concierge (grantInput); `launch` and `roles` are refused in C1. No grant is the default (a
+// read-and-notify Concierge); PRESET_GRANT is the conservative one Settings offers.
+import { CONCIERGE_LIMITS, CONCIERGE_ROLE, type ConciergeDigest, type ConciergeGrantSpec, type ConciergeGrantVerb, type ConciergeQuietHours, type ConciergeSettings } from "../../../packages/protocol/src/concierge"
+import type { Clock, StateStore } from "../backend/types"
+import { AgentError } from "../agent/errors"
+import { canonicalProject, GRANT_MAX_ACTIONS_PER_HOUR, GRANT_PROJECTS_MAX, parseDuration, validateGrant } from "../agent/policy"
+import { CONCIERGE_COLLECTION } from "./notes"
+
+const KEY = "settings"
+export const BRAIN_UNSUPPORTED = "Brain is not available to the Concierge yet: its tools are an exact allow-list, and Brain's MCP tools cannot be pinned by name"
+const FIELDS = new Set(["where", "machineID", "directory", "model", "grant", "connectors", "timeZone", "quietHours", "quietAllowsUrgent", "digests", "expectedRevision"])
+const GRANT_FIELDS = new Set(["allow", "projects", "permissions", "allowAlways", "expires", "maxActionsPerHour"])
+export const CONCIERGE_GRANT_VERBS: readonly ConciergeGrantVerb[] = ["approve", "deny", "answer", "prompt", "stop"]
+const MACHINE = /^[A-Za-z0-9._-]{1,80}$/
+const MODEL = /^[A-Za-z0-9._-]{1,80}\/[!-~]{1,200}$/
+const CLOCK = /^([01]\d|2[0-3]):[0-5]\d$/
+const EXPIRES = /^(\d{1,4})([hd])$/
+const DIRECTORY_MAX = 4096
+const HOUR_MS = 3_600_000
+const EXPIRES_MAX_MS = 30 * 24 * HOUR_MS
+
+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)
+
+export function defaultSettings(timeZone = "UTC"): ConciergeSettings {
+  return { enabled: false, where: "machine", connectors: { brain: false }, timeZone, quietAllowsUrgent: true, digests: [], revision: 0 }
+}
+
+/** The conservative grant Settings offers: answer and deny; approve read/edit inside the projects; never shell push/rm; 7 days. */
+export const PRESET_GRANT = (projects: readonly string[]): ConciergeGrantSpec => ({
+  allow: ["answer", "deny", "approve"],
+  projects: [...projects],
+  permissions: { allow: ["read", "edit"], never: ["shell:git push*", "shell:rm *"] },
+  allowAlways: false,
+  expires: "7d",
+  maxActionsPerHour: 60,
+})
+
+/** The grant routes' body for a Concierge grant spec (holder @@concierge). */
+export function grantInput(spec: ConciergeGrantSpec): Record<string, unknown> {
+  return {
+    holder: `@@${CONCIERGE_ROLE}`,
+    scope: { projects: [...spec.projects] },
+    allow: [...spec.allow],
+    permissions: { allow: [...spec.permissions.allow], never: [...spec.permissions.never] },
+    // (CON-13 decision) Never "always" for the Concierge, whatever an older stored spec says.
+    allowAlways: false,
+    expires: spec.expires,
+    maxActionsPerHour: spec.maxActionsPerHour,
+  }
+}
+
+export function validTimeZone(value: unknown): value is string {
+  if (typeof value !== "string" || !value || value.length > 64) return false
+  try {
+    new Intl.DateTimeFormat("en-GB", { timeZone: value })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function grantSpec(raw: unknown): ConciergeGrantSpec {
+  if (!isObject(raw)) throw invalid("grant is {allow, projects, permissions?, allowAlways?, expires?, maxActionsPerHour?}")
+  for (const key of Object.keys(raw)) if (!GRANT_FIELDS.has(key)) throw invalid(`Unknown grant field ${key.slice(0, 40)}`)
+  if (!Array.isArray(raw.allow) || raw.allow.length === 0) throw invalid(`grant.allow lists the verbs: ${CONCIERGE_GRANT_VERBS.join(", ")}`)
+  const allow: ConciergeGrantVerb[] = []
+  for (const verb of raw.allow) {
+    if (verb === "launch" || verb === "roles") throw invalid(`grant.allow: the Concierge cannot hold ${verb} in this version`)
+    if (!CONCIERGE_GRANT_VERBS.includes(verb)) throw invalid(`grant.allow: unknown verb ${String(verb).slice(0, 40)}`)
+    if (!allow.includes(verb)) allow.push(verb)
+  }
+  if (!Array.isArray(raw.projects) || raw.projects.length === 0 || raw.projects.length > GRANT_PROJECTS_MAX) throw invalid(`grant.projects lists 1–${GRANT_PROJECTS_MAX} project directories`)
+  const projects: string[] = []
+  for (const item of raw.projects) {
+    const canonical = canonicalProject(item as string)
+    if (canonical === undefined) throw invalid(`grant.projects: ${String(item).slice(0, 80)} is not an absolute project directory`)
+    if (!projects.includes(canonical)) projects.push(canonical)
+  }
+  let permissions = { allow: [] as string[], never: [] as string[] }
+  if (raw.permissions !== undefined) {
+    if (!isObject(raw.permissions)) throw invalid("grant.permissions is {allow?, never?}")
+    permissions = { allow: (raw.permissions.allow ?? []) as string[], never: (raw.permissions.never ?? []) as string[] }
+  }
+  if (raw.allowAlways !== undefined && typeof raw.allowAlways !== "boolean") throw invalid("grant.allowAlways is true or false")
+  if (raw.allowAlways === true) throw invalid("grant.allowAlways: the Concierge never approves “always” (that is always your tap)")
+  const expires = raw.expires ?? "30d"
+  const match = typeof expires === "string" ? EXPIRES.exec(expires) : null
+  const ms = match ? parseDuration(expires) : undefined
+  if (ms === undefined || ms < HOUR_MS || ms > EXPIRES_MAX_MS) throw invalid('grant.expires is "1h" to "30d"')
+  const cap = raw.maxActionsPerHour ?? 60
+  if (!Number.isInteger(cap) || (cap as number) < 1 || (cap as number) > GRANT_MAX_ACTIONS_PER_HOUR) throw invalid(`grant.maxActionsPerHour is a whole number 1–${GRANT_MAX_ACTIONS_PER_HOUR}`)
+  const spec: ConciergeGrantSpec = { allow, projects, permissions, allowAlways: false, expires: expires as string, maxActionsPerHour: cap as number }
+  // The grant validator has the last word on patterns (the same rules as every grant).
+  const checked = validateGrant(grantInput(spec))
+  return { ...spec, permissions: { allow: [...checked.permissions.allow], never: [...checked.permissions.never] } }
+}
+
+function quietHours(raw: unknown): ConciergeQuietHours {
+  if (!isObject(raw) || Object.keys(raw).some((k) => !["start", "end", "timeZone"].includes(k))) throw invalid("quietHours is {start, end, timeZone}")
+  if (typeof raw.start !== "string" || !CLOCK.test(raw.start) || typeof raw.end !== "string" || !CLOCK.test(raw.end)) throw invalid("quietHours start and end are HH:MM")
+  if (!validTimeZone(raw.timeZone)) throw invalid("quietHours.timeZone is an IANA time zone")
+  return { start: raw.start, end: raw.end, timeZone: raw.timeZone }
+}
+
+function digests(raw: unknown): ConciergeDigest[] {
+  if (!Array.isArray(raw) || raw.length > CONCIERGE_LIMITS.digests) throw invalid(`digests lists at most ${CONCIERGE_LIMITS.digests} entries`)
+  return raw.map((d) => {
+    if (!isObject(d) || Object.keys(d).some((k) => k !== "at" && k !== "days")) throw invalid("a digest is {at, days?}")
+    if (typeof d.at !== "string" || !CLOCK.test(d.at)) throw invalid("digest.at is HH:MM")
+    if (d.days === undefined) return { at: d.at }
+    if (!Array.isArray(d.days) || d.days.length === 0 || d.days.length > 7 || d.days.some((n) => !Number.isInteger(n) || n < 0 || n > 6) || new Set(d.days).size !== d.days.length) {
+      throw invalid("digest.days lists weekdays 0–6 (Sunday is 0)")
+    }
+    return { at: d.at, days: [...(d.days as (0 | 1 | 2 | 3 | 4 | 5 | 6)[])].sort() }
+  })
+}
+
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/
+
+/**
+ * The settings after a partial update by the user. Throws invalid, unsupported (hosted) or conflict (revision).
+ * Does not bump the revision (the store does).
+ */
+export function parseSettingsPatch(body: unknown, current: ConciergeSettings): ConciergeSettings {
+  if (!isObject(body)) throw invalid("The body is a partial settings object with expectedRevision")
+  for (const key of Object.keys(body)) {
+    if (key === "enabled") throw invalid("enabled changes through POST /api/agent/concierge/enable or /disable")
+    if (!FIELDS.has(key)) throw invalid(`Unknown or read-only field ${key.slice(0, 40)}`)
+  }
+  const expected = body.expectedRevision
+  if (!Number.isSafeInteger(expected)) throw invalid("expectedRevision is required")
+  if (expected !== current.revision) throw new AgentError("conflict", "The Concierge settings changed meanwhile", { extra: { currentRevision: current.revision } })
+  let next: { -readonly [K in keyof ConciergeSettings]: ConciergeSettings[K] } = { ...current }
+  const drop = (key: "machineID" | "directory" | "model" | "grant" | "quietHours") => {
+    const { [key]: _gone, ...rest } = next
+    next = rest as typeof next
+  }
+  if (body.where !== undefined) {
+    if (body.where === "hosted") throw new AgentError("unsupported", "A hosted Concierge is not available", { extra: { feature: "conciergeHosted" } })
+    if (body.where !== "machine") throw invalid('where is "machine"')
+  }
+  if (body.machineID !== undefined) {
+    if (body.machineID === null) drop("machineID")
+    else if (typeof body.machineID !== "string" || !MACHINE.test(body.machineID)) throw invalid("machineID is malformed")
+    else next.machineID = body.machineID
+  }
+  if (body.directory !== undefined) {
+    if (body.directory === null) drop("directory")
+    else {
+      const raw = body.directory
+      const canonical = typeof raw === "string" && raw.length <= DIRECTORY_MAX && !CONTROL.test(raw) ? canonicalProject(raw) : undefined
+      if (canonical === undefined || !canonical.startsWith("/")) throw invalid("directory is an absolute directory on the machine (a git repo under its workspace roots)")
+      next.directory = canonical
+    }
+  }
+  if (body.model !== undefined) {
+    if (body.model === null) drop("model")
+    else if (typeof body.model !== "string" || !MODEL.test(body.model)) throw invalid("model is provider/model")
+    else next.model = body.model
+  }
+  if (body.grant !== undefined) {
+    if (body.grant === null) drop("grant")
+    else next.grant = grantSpec(body.grant)
+  }
+  if (body.connectors !== undefined) {
+    const c = body.connectors
+    if (!isObject(c) || Object.keys(c).some((k) => k !== "brain") || typeof c.brain !== "boolean") throw invalid("connectors is {brain: true|false}")
+    // The Concierge's tools are an exact allow-list; Brain's MCP tools cannot be named exactly across machines (and
+    // Code Mode would expose every MCP tool), so Brain is not offered in C1.
+    if (c.brain) throw new AgentError("unsupported", BRAIN_UNSUPPORTED, { extra: { feature: "conciergeBrain", reason: BRAIN_UNSUPPORTED } })
+    next.connectors = { brain: false }
+  }
+  if (body.timeZone !== undefined) {
+    if (!validTimeZone(body.timeZone)) throw invalid("timeZone is an IANA time zone")
+    next.timeZone = body.timeZone
+  }
+  if (body.quietHours !== undefined) {
+    if (body.quietHours === null) drop("quietHours")
+    else next.quietHours = quietHours(body.quietHours)
+  }
+  if (body.quietAllowsUrgent !== undefined) {
+    if (typeof body.quietAllowsUrgent !== "boolean") throw invalid("quietAllowsUrgent is true or false")
+    next.quietAllowsUrgent = body.quietAllowsUrgent
+  }
+  if (body.digests !== undefined) next.digests = digests(body.digests)
+  return next
+}
+
+/** The user's settings record: version-checked writes, revision bumped by every write. */
+export class SettingsStore {
+  constructor(
+    private readonly state: StateStore,
+    private readonly now: Clock = Date.now,
+  ) {}
+
+  async get(userID: string): Promise<ConciergeSettings> {
+    return (await this.state.get<ConciergeSettings>(userID, CONCIERGE_COLLECTION, KEY))?.value ?? defaultSettings()
+  }
+
+  /** Applies `change` to the stored settings (re-read on a lost race; `change` may throw) and stores revision + 1. */
+  async update(userID: string, change: (current: ConciergeSettings) => ConciergeSettings): Promise<ConciergeSettings> {
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const stored = await this.state.get<ConciergeSettings>(userID, CONCIERGE_COLLECTION, KEY)
+      const current = stored?.value ?? defaultSettings()
+      const next: ConciergeSettings = { ...change(current), revision: current.revision + 1, updatedAt: this.now() }
+      const put = await this.state.put(userID, CONCIERGE_COLLECTION, KEY, next, { ifVersion: stored?.version ?? 0 })
+      if (put.ok) return next
+    }
+    throw new AgentError("conflict", "The Concierge settings kept changing; retry")
+  }
+}