@huynle/hub 0.7.3 → 0.8.0

package/src/central/agent/idempotency.ts

@@ -0,0 +1,133 @@
+// Route-level Idempotency-Key handling shared by the /api/agent create routes (contract: IDEMPOTENCY_KEY,
+// IDEMPOTENCY_TTL_MS; per user and per route). Two compatible modes:
+//
+// - Answer replay (RouteIdempotency.run, extracted from the profile routes of HWA-14): the first request with a
+//   key reserves it (ifVersion 0), runs, and stores its answer; a repeat with the same body within the TTL gets
+//   that answer again; another body under the key is 409 conflict, and so is a repeat while the first is still
+//   running. A failed request frees its key. Records live in a StateStore collection of the caller's choosing,
+//   keyed by sha256(route, key); expired ones are pruned as keys are used.
+// - Store-level (the workspace, assignment and launch stores keep the key next to the record they create, so the
+//   claim and the record cannot drift apart): the route only reads and validates the header (idempotencyKeyOf)
+//   and answers with storeAnswer.
+//
+// Both modes look the same to clients: the header is `Idempotency-Key`, a malformed key is 400 invalid with the
+// same wording, another body under a live key is 409 conflict, and a replay carries `idempotent-replayed: true`.
+import { createHash } from "node:crypto"
+import { IDEMPOTENCY_KEY, IDEMPOTENCY_TTL_MS } from "../../protocol"
+import type { Clock, StateStore } from "../backend/types"
+import { AgentError } from "./errors"
+
+export const IDEMPOTENCY_HEADER = "idempotency-key"
+export const REPLAYED_HEADER = "idempotent-replayed"
+const BAD_KEY = "Idempotency-Key must be 1–200 of A-Z a-z 0-9 _ . : -"
+
+export const IDEMPOTENCY_LIMITS = {
+  ttlMs: IDEMPOTENCY_TTL_MS,
+  /** A reservation whose request never finished is taken over after this long. */
+  pendingMs: 60_000,
+  /** Live keys per user (per collection). */
+  keysPerUser: 1_000,
+} as const
+
+interface Record_ {
+  readonly v: 1
+  readonly hash: string
+  readonly at: number
+  readonly state: "pending" | "done"
+  readonly status?: number
+  readonly body?: unknown
+}
+
+export interface Answer {
+  readonly status: number
+  readonly body: unknown
+}
+
+const NO_STORE = { "cache-control": "no-store" }
+const sha256 = (text: string) => createHash("sha256").update(text).digest("hex")
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** JSON with sorted keys and undefined members dropped (the same body in any key order compares equal). */
+export function canonicalBody(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalBody).join(",")}]`
+  if (isRecord(value)) {
+    const keys = Object.keys(value)
+      .filter((k) => value[k] !== undefined)
+      .sort()
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalBody(value[k])}`).join(",")}}`
+  }
+  return JSON.stringify(value)
+}
+
+/** The request's Idempotency-Key (undefined when absent; 400 invalid when malformed). */
+export function idempotencyKeyOf(request: Request): string | undefined {
+  const key = request.headers.get(IDEMPOTENCY_HEADER)
+  if (key === null) return undefined
+  if (!IDEMPOTENCY_KEY.test(key)) throw new AgentError("invalid", BAD_KEY)
+  return key
+}
+
+/** The answer of a store-level idempotent create: `status` when it created, 200 + the replay header when not. */
+export function storeAnswer(created: boolean, body: unknown, status = 201): Response {
+  return respond({ status: created ? status : 200, body }, !created)
+}
+
+export class RouteIdempotency {
+  private readonly state: StateStore
+  private readonly collection: string
+  private readonly now: Clock
+
+  constructor(options: { readonly state: StateStore; readonly collection: string; readonly now?: Clock }) {
+    this.state = options.state
+    this.collection = options.collection
+    this.now = options.now ?? Date.now
+  }
+
+  /** Runs `perform` once per (user, route, key, body); without a key it simply runs. */
+  async run(userID: string, route: string, key: string | null, body: unknown, perform: () => Promise<Answer>): Promise<Response> {
+    if (key === null) return respond(await perform(), false)
+    if (!IDEMPOTENCY_KEY.test(key)) throw new AgentError("invalid", BAD_KEY)
+    const id = sha256(`${route}\n${key}`)
+    const hash = sha256(canonicalBody(body))
+    let reserved: number | undefined
+    for (let attempt = 0; attempt < 4 && reserved === undefined; attempt++) {
+      const existing = await this.state.get<Record_>(userID, this.collection, id)
+      const now = this.now()
+      const live = existing && now - existing.value.at < (existing.value.state === "pending" ? IDEMPOTENCY_LIMITS.pendingMs : IDEMPOTENCY_LIMITS.ttlMs)
+      if (existing && live) {
+        if (existing.value.hash !== hash) throw new AgentError("conflict", "This Idempotency-Key was used with another body", { hint: "Use a new key" })
+        if (existing.value.state === "done") return respond({ status: existing.value.status!, body: existing.value.body }, true)
+        throw new AgentError("conflict", "A request with this Idempotency-Key is still running", { hint: "Retry shortly" })
+      }
+      if (!existing) await this.prune(userID)
+      const put = await this.state.put<Record_>(userID, this.collection, id, { v: 1, hash, at: now, state: "pending" }, { ifVersion: existing?.version ?? 0 })
+      if (put.ok) reserved = put.version
+    }
+    if (reserved === undefined) throw new AgentError("conflict", "A request with this Idempotency-Key is still running", { hint: "Retry shortly" })
+    let answer: Answer
+    try {
+      answer = await perform()
+    } catch (cause) {
+      await this.state.delete(userID, this.collection, id, { ifVersion: reserved }).catch(() => {})
+      throw cause
+    }
+    await this.state.put<Record_>(userID, this.collection, id, { v: 1, hash, at: this.now(), state: "done", status: answer.status, body: answer.body }, { ifVersion: reserved })
+    return respond(answer, false)
+  }
+
+  /** Drops expired keys; refuses a new one past keysPerUser live keys. */
+  private async prune(userID: string): Promise<void> {
+    const now = this.now()
+    let live = 0
+    for (const entry of await this.state.list<Record_>(userID, this.collection)) {
+      const ttl = entry.value.state === "pending" ? IDEMPOTENCY_LIMITS.pendingMs : IDEMPOTENCY_LIMITS.ttlMs
+      if (now - entry.value.at >= ttl) await this.state.delete(userID, this.collection, entry.key, { ifVersion: entry.version })
+      else live++
+    }
+    if (live >= IDEMPOTENCY_LIMITS.keysPerUser) throw new AgentError("rate_limited", `At most ${IDEMPOTENCY_LIMITS.keysPerUser} live Idempotency-Keys per user`, { extra: { retryAfter: 3600 } })
+  }
+}
+
+function respond(answer: Answer, replayed: boolean): Response {
+  return Response.json(answer.body, { status: answer.status, headers: { ...NO_STORE, ...(replayed ? { [REPLAYED_HEADER]: "true" } : {}) } })
+}

package/src/central/agent/intent-routes.ts

@@ -0,0 +1,116 @@
+// Session intent routes (CON-02; contract: "Session intent (CON-02)" in docs/plans/2026-11-01-concierge-contracts.md).
+//
+//   GET /api/agent/sessions/:addr/intent                               → {intent: SessionIntent | null}
+//       users; app tokens holding sessions:read; session tokens (the session read rules: any of the user's
+//       sessions, scoped by team discovery when the hub has it)
+//   PUT /api/agent/sessions/:addr/intent {text: string | null, expectedRevision}  → {intent: SessionIntent | null}
+//       users (source user); app tokens holding sessions:manage (source user, `by` the app); a session token for
+//       ITS OWN session only (source self; another session is 403 forbidden). null clears the writer's layer, down
+//       to the next source. A stale expectedRevision is 409 conflict {currentRevision}. (CON-10) Users only:
+//       {source: "prompt", text: null, expectedRevision} clears the first-prompt intent (a wrong one), down to the
+//       next source; the first prompt stays used up, so a later prompt never refills it.
+//
+// Answers carry the effective intent: the stored one, else the session's non-placeholder title (source title, the
+// record's revision, 0 when nothing was ever stored), else null. Another user's session is 404 not_found (address
+// resolution is per caller). The text is untrusted data: bounded, sanitised and never interpreted. Each change is
+// in the admin audit (no text) and the journal (`session.intent {source, revision}`, from SessionIntents).
+import type { SessionIntent } from "../../protocol"
+import type { Registry } from "../registry"
+import type { Store } from "../store"
+import type { AgentActor } from "./actor"
+import { boundedJson } from "./body"
+import type { Directory, DirectoryEntry } from "./directory"
+import { AgentError } from "./errors"
+import { type IntentWrite, type SessionIntents, titleIntent } from "./intents"
+import { AGENT_PREFIX, type AgentContext, type AgentRoute } from "./routes"
+import type { TeamDiscovery } from "../teams/discovery"
+
+/** A PUT body is one short line of text and a revision. */
+const BODY_MAX = 16 * 1024
+const FIELDS = new Set(["text", "expectedRevision", "source"])
+
+export interface IntentRoutesDeps {
+  readonly intents: SessionIntents
+  readonly directory: Directory
+  /** The live title (the read fallback); the directory's last known title otherwise. */
+  readonly registry?: Pick<Registry, "sessionTenant" | "session">
+  readonly store: Pick<Store, "audit">
+  /** Team-aware discovery (HWA-40): team-scoped callers read only sessions they may see. */
+  readonly discovery?: TeamDiscovery
+}
+
+const NO_STORE = { "cache-control": "no-store" }
+const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
+
+/** Who wrote: user, app:<tokenID>, or the session's ID (as launches record `by`). */
+function writer(actor: AgentActor): string {
+  switch (actor.kind) {
+    case "user":
+      return "user"
+    case "app":
+      return `app:${actor.tokenID}`
+    case "session":
+      return actor.sessionID
+  }
+}
+
+async function readWrite(request: Request): Promise<Pick<IntentWrite, "text" | "expectedRevision"> & { readonly clearPrompt?: true }> {
+  const body = await boundedJson(request, BODY_MAX)
+  if (typeof body !== "object" || body === null || Array.isArray(body)) throw new AgentError("invalid", "Expected a JSON object {text, expectedRevision}")
+  const fields = body as Record<string, unknown>
+  for (const key of Object.keys(fields)) if (!FIELDS.has(key)) throw new AgentError("invalid", `Unknown field ${key}`)
+  const { text, expectedRevision } = fields
+  if (text !== null && typeof text !== "string") throw new AgentError("invalid", "text is a string, or null to clear")
+  if (!Number.isSafeInteger(expectedRevision) || (expectedRevision as number) < 0) {
+    throw new AgentError("invalid", "expectedRevision is the intent's revision you read (0 when none was stored)")
+  }
+  // (CON-10) {source: "prompt", text: null}: the user clears the first-prompt intent (down to the title).
+  if (fields.source !== undefined && (fields.source !== "prompt" || text !== null)) throw new AgentError("invalid", 'source is only "prompt", with text null (clears the first-prompt intent)')
+  return { text, expectedRevision: expectedRevision as number, ...(fields.source === "prompt" ? { clearPrompt: true as const } : {}) }
+}
+
+export function intentRoutes(deps: IntentRoutesDeps): AgentRoute[] {
+  const { intents, directory } = deps
+
+  /** The session an address names for this caller (team-scoped when discovery is given); not_found otherwise. */
+  async function resolve(userID: string, actor: AgentActor, addr: string): Promise<DirectoryEntry> {
+    if (deps.discovery) return deps.discovery.resolveOne(await deps.discovery.census(userID, actor), addr)
+    return directory.resolveOne(userID, addr)
+  }
+
+  /** The stored intent, else the title fallback, else null. */
+  async function effective(userID: string, entry: DirectoryEntry): Promise<SessionIntent | null> {
+    const stored = await intents.read(userID, entry.sessionID)
+    if (stored) return stored
+    const live = deps.registry && deps.registry.sessionTenant(entry.sessionID) === userID ? deps.registry.session(entry.sessionID) : undefined
+    const title = live?.title ?? entry.title
+    return titleIntent(entry.sessionID, title, await intents.revision(userID, entry.sessionID), live?.updated ?? entry.lastSeen ?? 0) ?? null
+  }
+
+  return [
+    {
+      method: "GET",
+      path: `${AGENT_PREFIX}/sessions/:addr/intent`,
+      allow: { session: true, scope: "sessions:read" },
+      handle: async ({ user, actor, params }) => ok({ intent: await effective(user.id, await resolve(user.id, actor, params.addr!)) }),
+    },
+    {
+      method: "PUT",
+      path: `${AGENT_PREFIX}/sessions/:addr/intent`,
+      allow: { session: true, scope: "sessions:manage" },
+      async handle(context: AgentContext) {
+        const { user, actor, params } = context
+        const { clearPrompt, ...write } = await readWrite(context.request)
+        const entry = await resolve(user.id, actor, params.addr!)
+        if (actor.kind === "session" && entry.sessionID !== actor.sessionID) throw new AgentError("forbidden", "A session token can only set its own session's intent")
+        if (clearPrompt && actor.kind !== "user") throw new AgentError("forbidden", "Only the user clears a session's first-prompt intent")
+        const before = await intents.revision(user.id, entry.sessionID)
+        await intents.set(user.id, entry.sessionID, { ...write, source: clearPrompt ? "prompt" : actor.kind === "session" ? "self" : "user", by: writer(actor) })
+        if ((await intents.revision(user.id, entry.sessionID)) !== before) {
+          await deps.store.audit({ actor: user.id, action: write.text === null ? "session.intent.clear" : "session.intent", target: entry.sessionID, detail: actor.kind })
+        }
+        return ok({ intent: await effective(user.id, entry) })
+      },
+    },
+  ]
+}