@huynle/hub 0.7.3 → 0.8.0

package/src/central/agent/intents.ts

@@ -0,0 +1,505 @@
+// Session intents (CON-02; contract: "Session intent (CON-02)" in docs/plans/2026-11-01-concierge-contracts.md):
+// what a session is for, in one untrusted line the hub keeps beside the session (never on AgentSession, so 2000
+// sessions × 280 characters do not bloat the user record).
+//
+// Storage: StateStore collection `session-intents` (tenant = hub user, key = session ID), one record per session
+// holding a LAYER per source. Precedence user > launch > self > prompt: the highest layer present is the intent, so
+// a lower source never replaces a higher one, and clearing a layer (text null) falls back to the next one. `title`
+// is never stored: reads fall back to the session's non-placeholder title (titleIntent).
+//   - user:   PUT by the user, or an app token holding sessions:manage (`by` tells them apart)
+//   - launch: the launch spec's `intent`, stored when the launched session is identified
+//   - self:   PUT by a session for itself
+//   - prompt: derived ONCE, from the first prompt the hub carries for the session (console turn, launch prompt,
+//             agent prompt through acting): first line, then first sentence, cut to 280 characters, no model call.
+//
+// `revision` counts changes of the EFFECTIVE intent (text or source), 1 for the first; a write that only changes a
+// layer beneath it bumps nothing. Writers send `expectedRevision` (0 before anything was stored); a stale one is
+// 409 conflict {currentRevision}. Records are version-checked (updateVersioned), so concurrent writers retry.
+// Every change of the effective intent appends `session.intent {source, revision}` (family manage) to the journal:
+// never the text. `source` is "title" once nothing is stored any more.
+//
+// Reads on request paths use many(ids): one get per listed session, never the whole collection (the StateStore has
+// no batch get; the gets run concurrently, pipelined on Postgres). Retention (IntentRetention, one leader
+// "session-intents", first run a minute after election unless this process swept within the interval, then every
+// 6 h) keeps every record of an online session (the registry decides, not the directory, which keeps at most 2000
+// records per user and may have evicted an offline one) and drops records of deleted sessions (deletedAt;
+// Directory.markDeleted is not called today) and of sessions neither seen (directory lastSeen, or a sweep while
+// online) nor written for 30 days. A dropped record's revision starts over at 0, as the contract has it before
+// anything is stored (coordinator decision, round-3 review): a client that held a revision across a 30-day-offline
+// deletion could write over a newer intent at the same revision (ABA). That window is accepted.
+//
+// The text is untrusted data: sanitised (control, ANSI, bidi and zero-width characters go), folded onto one line,
+// at most INTENT_MAX characters. The hub never interprets it.
+import { INTENT_MAX, type IntentSource, type SessionIntent } from "../../protocol"
+import type { Actions } from "../actions"
+import { realTimers } from "../backend/memory-bus"
+import type { StateStore, Timers } from "../backend/types"
+import { sanitizeText } from "./envelope"
+import { AgentError } from "./errors"
+import type { AgentEvents, EventInput } from "./events"
+import { isPlaceholderTitle } from "./names"
+import { updateVersioned } from "./versioned"
+
+export const INTENTS = "session-intents"
+
+/** The sources the hub stores (title is a read fallback only). */
+export type StoredSource = Exclude<IntentSource, "title">
+
+/** Highest precedence first. */
+export const INTENT_ORDER: readonly StoredSource[] = ["user", "launch", "self", "prompt"]
+
+/** Raw input longer than this is refused before it is cleaned (bounds the work on hostile input). */
+const RAW_MAX = 4 * 1024
+
+interface Layer {
+  readonly text: string
+  readonly at: number
+  readonly by?: string
+}
+
+/** A session's stored record. */
+interface StoredIntent {
+  readonly sessionID: string
+  readonly layers: Partial<Record<StoredSource, Layer>>
+  readonly revision: number
+  /** The first prompt was seen (it is derived once, even when a higher layer hides it). */
+  readonly prompted?: true
+  /** The last write (any layer), for retention; older records fall back to their newest layer. */
+  readonly touched?: number
+  /** The last time a retention sweep saw the session online. */
+  readonly seen?: number
+}
+
+
+
+/** When a record was last written. */
+const touchedAt = (record: StoredIntent) => record.touched ?? Math.max(0, ...Object.values(record.layers).map((l) => l?.at ?? 0))
+
+/**
+ * What retention knows of a session: online from the registry (whatever the directory holds), lastSeen and deletedAt
+ * from the directory when it has a record (it keeps at most 2000 per user, so an offline session may have none).
+ */
+export interface IntentSessionFacts {
+  readonly online: boolean
+  readonly lastSeen?: number
+  readonly deletedAt?: number
+}
+
+/** Records of sessions neither seen (directory, or a sweep while online) nor written this long are dropped. */
+export const INTENT_RETENTION_MS = 30 * 86_400_000
+/** A sweep re-stamps `seen` on an online session's record at most this often. */
+const SEEN_STEP_MS = 86_400_000
+
+/** Sanitised, one line, trimmed, cut to `max` characters (code points). */
+function clean(text: string, max = Infinity): string {
+  return Array.from(sanitizeText(text).replace(/\s+/g, " ").trim()).slice(0, max).join("").trimEnd()
+}
+
+/** A user, app, session or launch intent: sanitised, one line, 1–280 characters; anything else is 400 invalid. */
+export function intentText(input: unknown): string {
+  const problem = `intent is text of 1–${INTENT_MAX} characters on one line`
+  if (typeof input !== "string" || input.length > RAW_MAX) throw new AgentError("invalid", problem)
+  const text = clean(input)
+  const length = Array.from(text).length
+  if (length === 0 || length > INTENT_MAX) throw new AgentError("invalid", problem)
+  return text
+}
+
+/** The intent of a first prompt: its first non-blank line, then that line's first sentence, ≤ 280 characters. */
+export function deriveIntent(prompt: string): string | undefined {
+  const line = sanitizeText(prompt.slice(0, RAW_MAX))
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.length > 0)
+  if (line === undefined) return undefined
+  return clean(firstSentence(line), INTENT_MAX) || undefined
+}
+
+/** Common abbreviations a sentence does not end at ("e.g. the docs", "Bun vs. Node"). */
+const ABBREVIATIONS = new Set(["e.g", "i.e", "etc", "vs", "cf", "approx", "incl", "mr", "mrs", "ms", "dr", "st", "u.s", "u.k", "a.m", "p.m"])
+
+/** The line up to its first sentence end ([.!?] then a space or the end) that does not close an abbreviation. */
+function firstSentence(line: string): string {
+  const end = /[.!?](?=\s|$)/g
+  for (let match = end.exec(line); match; match = end.exec(line)) {
+    const word = /(\S+)$/.exec(line.slice(0, match.index))?.[1]?.toLowerCase().replace(/^[("'[]+/, "")
+    if (match[0] === "." && word !== undefined && ABBREVIATIONS.has(word)) continue
+    return line.slice(0, match.index + 1)
+  }
+  return line
+}
+
+/** The read fallback: the session's title when it is not a placeholder, as source "title". */
+export function titleIntent(sessionID: string, title: string | undefined, revision: number, updatedAt: number): SessionIntent | undefined {
+  if (isPlaceholderTitle(title)) return undefined
+  const text = clean(title!, INTENT_MAX)
+  return text ? { sessionID, text, source: "title", revision, updatedAt } : undefined
+}
+
+/** The journal event of a changed intent: its source and revision, never the text. */
+export const intentEvent = (sessionID: string, source: IntentSource, revision: number): EventInput => ({
+  type: "session.intent",
+  family: "manage",
+  subject: { sessionID },
+  data: { source, revision },
+})
+
+/** The effective intent of a record (its highest layer). */
+function effective(record: StoredIntent | undefined): SessionIntent | undefined {
+  if (!record) return undefined
+  for (const source of INTENT_ORDER) {
+    const layer = record.layers[source]
+    if (layer) return { sessionID: record.sessionID, text: layer.text, source, revision: record.revision, updatedAt: layer.at, ...(layer.by !== undefined ? { by: layer.by } : {}) }
+  }
+  return undefined
+}
+
+const sameIntent = (a: SessionIntent | undefined, b: SessionIntent | undefined) => a?.text === b?.text && a?.source === b?.source
+
+/** (CON-10) A Concierge proposal's prompt the user ran (Do it): its session, text and when it was answered. */
+export interface ProposedPrompt {
+  readonly sessionID: string
+  readonly text: string
+  readonly at: number
+}
+
+/** The old build derived a run proposal's prompt in the background, right after the answer: within this window. */
+export const PROPOSAL_DERIVE_WINDOW_MS = 60_000
+
+export interface SessionIntentsDeps {
+  readonly state: StateStore
+  readonly now?: () => number
+  /** The journal: `session.intent` on every change of an effective intent. */
+  readonly events?: Pick<AgentEvents, "append">
+  /** Every change of an effective intent (the console stream: IDs, source and revision only, never the text). */
+  readonly onChange?: (userID: string, sessionID: string, source: IntentSource, revision: number) => void
+}
+
+/** A write through the API: user, app (as source user) or the session itself (source self). */
+export interface IntentWrite {
+  readonly source: StoredSource
+  /** Validated by intentText here; null clears this source's layer. */
+  readonly text: string | null
+  readonly expectedRevision: number
+  /** Party key of the writer. */
+  readonly by?: string
+}
+
+export class SessionIntents {
+  private readonly now: () => number
+
+  constructor(private readonly deps: SessionIntentsDeps) {
+    this.now = deps.now ?? Date.now
+  }
+
+  /** The stored effective intent (undefined when nothing is stored: callers fall back to the title). */
+  async read(userID: string, sessionID: string): Promise<SessionIntent | undefined> {
+    return effective(await this.record(userID, sessionID))
+  }
+
+  /** The record's revision (0 before anything was stored, or after retention dropped it). */
+  async revision(userID: string, sessionID: string): Promise<number> {
+    return (await this.record(userID, sessionID))?.revision ?? 0
+  }
+
+  /** Every stored effective intent of a user, by session ID (lists the whole collection: not for request paths; use many). */
+  async all(userID: string): Promise<Map<string, SessionIntent>> {
+    const out = new Map<string, SessionIntent>()
+    for (const { key, value } of await this.deps.state.list<StoredIntent>(userID, INTENTS)) {
+      const intent = effective({ ...value, sessionID: key })
+      if (intent) out.set(key, intent)
+    }
+    return out
+  }
+
+  /** The stored effective intents of these sessions (one read each, concurrently; never the whole collection). */
+  async many(userID: string, sessionIDs: Iterable<string>): Promise<Map<string, SessionIntent>> {
+    const ids = [...new Set(sessionIDs)]
+    const records = await Promise.all(ids.map((id) => this.record(userID, id)))
+    const out = new Map<string, SessionIntent>()
+    records.forEach((record, i) => {
+      const intent = effective(record)
+      if (intent) out.set(ids[i]!, intent)
+    })
+    return out
+  }
+
+  /**
+   * Retention. A record is kept while its session is online (the sweep stamps `seen` then); it is dropped when its
+   * session is deleted, or when it was neither seen (directory lastSeen, or a sweep while online) nor written for
+   * INTENT_RETENTION_MS. A session the directory has no record of is judged the same way (offline, lastSeen unknown).
+   * Deletes and stamps are version-checked (a concurrent write wins); a dropped record's revision starts over at 0.
+   * Answers how many records were dropped.
+   */
+  async sweep(userID: string, facts: (sessionID: string) => IntentSessionFacts, options: { readonly retentionMs?: number } = {}): Promise<number> {
+    const retention = options.retentionMs ?? INTENT_RETENTION_MS
+    const t = this.now()
+    let dropped = 0
+    for (const { key, value, version } of await this.deps.state.list<StoredIntent>(userID, INTENTS)) {
+      const session = facts(key)
+      if (session.online) {
+        if (t - (value.seen ?? 0) >= SEEN_STEP_MS) await this.deps.state.put(userID, INTENTS, key, { ...value, seen: t }, { ifVersion: version })
+        continue
+      }
+      const last = Math.max(session.lastSeen ?? 0, touchedAt(value), value.seen ?? 0)
+      if (session.deletedAt === undefined && t - last <= retention) continue
+      if ((await this.deps.state.delete(userID, INTENTS, key, { ifVersion: version })).ok) dropped++
+    }
+    return dropped
+  }
+
+  /** Sets (or with null clears) one source's layer under expectedRevision; answers the effective intent. */
+  async set(userID: string, sessionID: string, write: IntentWrite): Promise<SessionIntent | undefined> {
+    const text = write.text === null ? null : intentText(write.text)
+    return this.change(userID, sessionID, (current) => {
+      const revision = current?.revision ?? 0
+      if (write.expectedRevision !== revision) {
+        throw new AgentError("conflict", `The intent changed since you read it (revision ${revision} now)`, { extra: { currentRevision: revision } })
+      }
+      // (CON-10) Clearing the first-prompt layer is a change the user made even when a higher layer hides it: the
+      // revision moves (a stale client must re-read) and it is journaled and audited like any change.
+      const bump = write.source === "prompt" && text === null ? ({ bump: true } as const) : {}
+      return { layer: write.source, value: text === null ? null : { text, at: this.now(), ...(write.by !== undefined ? { by: write.by } : {}) }, ...bump }
+    })
+  }
+
+  /** The launch spec's intent, when its session is identified (validated by the launch spec). */
+  async storeLaunch(userID: string, sessionID: string, text: string, by?: string): Promise<void> {
+    const clean = intentText(text)
+    await this.change(userID, sessionID, () => ({ layer: "launch", value: { text: clean, at: this.now(), ...(by !== undefined ? { by } : {}) } }))
+  }
+
+  /** Derives the prompt layer from the session's first prompt (once); true when it was recorded now. */
+  async derive(userID: string, sessionID: string, prompt: string): Promise<boolean> {
+    const text = deriveIntent(prompt)
+    if (text === undefined) return false
+    let recorded = false
+    await this.change(userID, sessionID, (current) => {
+      if (current?.prompted) return undefined
+      recorded = true
+      return { layer: "prompt", value: { text, at: this.now() }, prompted: true }
+    })
+    return recorded
+  }
+
+  /**
+   * (CON-10) One-time correction of records the build before CON-09a wrote: it derived a Concierge-proposed prompt
+   * (run as the user when they tapped Do it) as the session's first-prompt intent. A prompt layer whose text is the
+   * derivation of such a proposal's prompt, written within PROPOSAL_DERIVE_WINDOW_MS after the proposal was answered,
+   * is cleared (the session falls back to its title); `prompted` stays, so a later prompt never fills it. Idempotent.
+   * Answers how many layers were cleared.
+   */
+  async correctProposed(userID: string, proposals: readonly ProposedPrompt[]): Promise<number> {
+    let cleared = 0
+    const bySession = new Map<string, ProposedPrompt[]>()
+    for (const p of proposals) bySession.set(p.sessionID, [...(bySession.get(p.sessionID) ?? []), p])
+    for (const [sessionID, list] of bySession) {
+      const layer = (await this.record(userID, sessionID))?.layers.prompt
+      if (!layer) continue
+      const derived = list.some((p) => deriveIntent(p.text) === layer.text && layer.at >= p.at && layer.at - p.at <= PROPOSAL_DERIVE_WINDOW_MS)
+      if (!derived) continue
+      let done = false
+      await this.change(userID, sessionID, (current) => {
+        if (current?.layers.prompt?.text !== layer.text || current.layers.prompt.at !== layer.at) return undefined
+        done = true
+        return { layer: "prompt", value: null }
+      })
+      if (done) cleared++
+    }
+    return cleared
+  }
+
+  private async record(userID: string, sessionID: string): Promise<StoredIntent | undefined> {
+    const value = (await this.deps.state.get<StoredIntent>(userID, INTENTS, sessionID))?.value
+    return value && { ...value, sessionID }
+  }
+
+  /**
+   * Applies one layer change (value null clears it; `plan` undefined leaves the record alone). The revision grows
+   * only when the effective intent changes, and only then is the event appended.
+   */
+  private async change(
+    userID: string,
+    sessionID: string,
+    plan: (current: StoredIntent | undefined) => { layer: StoredSource; value: Layer | null; prompted?: true; bump?: true } | undefined,
+  ): Promise<SessionIntent | undefined> {
+    let before: SessionIntent | undefined
+    let bumped = false
+    const written = await updateVersioned<StoredIntent>(this.deps.state, userID, INTENTS, sessionID, (stored) => {
+      const current = stored && { ...stored, sessionID }
+      before = effective(current)
+      bumped = false
+      const step = plan(current)
+      if (!step) return undefined
+      const layers = { ...current?.layers }
+      const old = layers[step.layer]
+      if (step.value === null) {
+        if (!old) return undefined
+        delete layers[step.layer]
+      } else {
+        if (old?.text === step.value.text && !step.prompted) return undefined
+        layers[step.layer] = old?.text === step.value.text ? old : step.value
+      }
+      const prompted = step.prompted || current?.prompted ? { prompted: true as const } : {}
+      const draft: StoredIntent = { sessionID, layers, revision: current?.revision ?? 0, ...prompted, touched: this.now(), ...(current?.seen !== undefined ? { seen: current.seen } : {}) }
+      bumped = !sameIntent(before, effective(draft)) || step.bump === true
+      return bumped ? { ...draft, revision: draft.revision + 1 } : draft
+    })
+    const after = written ? effective(written) : before
+    if (bumped && written) {
+      this.deps.onChange?.(userID, sessionID, after?.source ?? "title", written.revision)
+      await this.deps.events
+        ?.append(userID, intentEvent(sessionID, after?.source ?? "title", written.revision))
+        .catch((cause: unknown) => console.error(`[hub] session.intent event failed: ${(cause as Error).message}`))
+    }
+    return after
+  }
+}
+
+/** What reads embed (GET /sessions, /sessions/:addr, /who): the stored intent without writer details. */
+export const intentField = (intent: SessionIntent | undefined): { intent?: { text: string; source: IntentSource; revision: number } } =>
+  intent ? { intent: { text: intent.text, source: intent.source, revision: intent.revision } } : {}
+
+/**
+ * The shared action executor with the first-prompt derivation: the prompts the hub carries as human turns (the
+ * user's console turn or prompt, a launch prompt) go through Actions.prompt; once one was carried, the session
+ * owner's prompt layer is derived in the background (never delaying or failing the prompt). (CON-09a) Agents'
+ * prompts are deliveries (never through here), and a prompt the user only approved (a Concierge proposal, intent:
+ * false) is never a source.
+ */
+export function withPromptIntents<A extends Actions>(
+  actions: A,
+  intents: Pick<SessionIntents, "derive">,
+  tenant: (sessionID: string) => string | undefined,
+  title?: (sessionID: string) => string | undefined,
+): A {
+  return {
+    ...actions,
+    async prompt(input) {
+      // (CON-10) Only the session's own first prompt: a session that already has a real title had its first prompt
+      // elsewhere (typed in its terminal, before the hub carried any), so a later hub-carried prompt is not it. Read
+      // before the turn runs (the turn itself may generate the title).
+      // A launch's prompt (intent "first") is its session's first prompt even though the launch titled it already.
+      const first = input.intent === "first" || title === undefined || isPlaceholderTitle(title(input.sessionID))
+      const result = await actions.prompt(input)
+      const userID = result.outcome === "done" ? tenant(input.sessionID) : undefined
+      if (userID !== undefined && first && input.text && input.intent !== false) {
+        void intents.derive(userID, input.sessionID, input.text).catch((cause: unknown) => console.error(`[hub] intent derivation failed: ${(cause as Error).message}`))
+      }
+      return result
+    },
+  }
+}
+
+export interface IntentRetentionOptions {
+  readonly intents: Pick<SessionIntents, "sweep"> & Partial<Pick<SessionIntents, "correctProposed">>
+  /**
+   * (CON-10) The user's run Concierge proposal prompts (answered Do it): the first pass of this process corrects
+   * the prompt intents the build before CON-09a derived from them (SessionIntents.correctProposed), once per user.
+   */
+  readonly proposed?: (userID: string) => Promise<readonly ProposedPrompt[]>
+  /** The hub's user IDs (read at every run). */
+  readonly users: () => Iterable<string> | Promise<Iterable<string>>
+  /** The directory's facts about a user's sessions (read once per user per run). */
+  readonly facts: (userID: string) => (sessionID: string) => IntentSessionFacts
+  readonly intervalMs?: number
+  /** The first run after start (default a minute), or the rest of the interval when this process swept more recently. */
+  readonly firstDelayMs?: number
+  readonly now?: () => number
+  readonly timers?: Timers
+  readonly log?: (message: string) => void
+}
+
+/** Time between retention runs. */
+export const INTENT_RETENTION_INTERVAL_MS = 6 * 3_600_000
+
+/** The retention sweep of every user's session intents, every intervalMs while started (under a leader). */
+export class IntentRetention {
+  private readonly intervalMs: number
+  private readonly timers: Timers
+  private readonly log: (message: string) => void
+  private running: Promise<{ users: number; failures: number; dropped: number }> | undefined
+  private timer: unknown
+  private started = false
+  /** When this process last finished a pass (a re-election here does not redo it within the interval). */
+  private lastPassAt: number | undefined
+  /** (CON-10) Users whose proposal correction ran in this process. */
+  private readonly corrected = new Set<string>()
+
+  constructor(private readonly options: IntentRetentionOptions) {
+    this.intervalMs = options.intervalMs ?? INTENT_RETENTION_INTERVAL_MS
+    this.timers = options.timers ?? realTimers
+    this.log = options.log ?? ((message) => console.error(message))
+  }
+
+  /** One pass over every user (a failure is logged without IDs and the pass goes on); concurrent callers share it. */
+  runOnce(): Promise<{ users: number; failures: number; dropped: number }> {
+    this.running ??= this.pass().finally(() => {
+      this.running = undefined
+    })
+    return this.running
+  }
+
+  start(): void {
+    if (this.started) return
+    this.started = true
+    const first = this.options.firstDelayMs ?? 60_000
+    const sinceLast = this.lastPassAt === undefined ? Infinity : (this.options.now ?? Date.now)() - this.lastPassAt
+    this.schedule(Math.max(first, this.intervalMs - sinceLast))
+  }
+
+  stop(): void {
+    this.started = false
+    if (this.timer !== undefined) this.timers.clear(this.timer)
+    this.timer = undefined
+  }
+
+  private schedule(delayMs = this.intervalMs): void {
+    this.timer = this.timers.set(() => {
+      this.timer = undefined
+      void this.runOnce().finally(() => {
+        if (this.started) this.schedule()
+      })
+    }, delayMs)
+  }
+
+  /** (CON-10) The one-time proposal correction of a user (a failure is logged without IDs and retried next pass). */
+  private async correct(userID: string): Promise<void> {
+    const { proposed } = this.options
+    const correctProposed = this.options.intents.correctProposed?.bind(this.options.intents)
+    if (!proposed || !correctProposed || this.corrected.has(userID)) return
+    try {
+      const cleared = await correctProposed(userID, await proposed(userID))
+      this.corrected.add(userID)
+      if (cleared > 0) this.log(`[hub] session intent correction: cleared ${cleared} intent(s) derived from Concierge proposals`)
+    } catch {
+      // No error text: it could name sessions or Decisions (retried on the next pass).
+      this.log("[hub] session intent correction failed for a user; it is retried on the next pass")
+    }
+  }
+
+  private async pass(): Promise<{ users: number; failures: number; dropped: number }> {
+    let users = 0
+    let failures = 0
+    let dropped = 0
+    let list: Iterable<string>
+    try {
+      list = await this.options.users()
+    } catch (cause) {
+      this.log(`[hub] session intent retention could not list users: ${(cause as Error).message}`)
+      return { users, failures: 1, dropped }
+    }
+    for (const userID of list) {
+      users++
+      await this.correct(userID)
+      try {
+        dropped += await this.options.intents.sweep(userID, this.options.facts(userID))
+      } catch (cause) {
+        failures++
+        this.log(`[hub] session intent retention failed for a user: ${(cause as Error).message}`)
+      }
+    }
+    this.lastPassAt = (this.options.now ?? Date.now)()
+    return { users, failures, dropped }
+  }
+}