@huynle/hub 0.6.1 → 0.7.2

package/src/central/agent/events.ts

@@ -0,0 +1,277 @@
+// The canonical agent event journal (lifecycle design: Events; decision xwzersmm). One bounded journal per user of
+// compact events that GET /api/agent/events, MCP `events` and /api/agent/watch read:
+//
+//   {id: "evt_…", at, type, subject: {sessionID?, rootID?, messageID?, senderID?, launchID?, machineID?}, data}
+//
+// Payloads are built from allowlists here and nowhere else: never prompts, message bodies, titles, blocker
+// summaries, launch reasons or labels, credentials, or connection/pod/spoke IDs. Each record also keeps, for the
+// reader only, its scope family (session, manage, message, launch) and its audience (the parties of a message, who
+// started a launch), so an app or session token sees only what its scopes and identity allow.
+//
+// Storage is an EventLog (a Valkey stream per user in a cluster, process memory otherwise) bounded to
+// AGENT_EVENTS_MAX events and AGENT_EVENTS_AGE_MS. An event id is assigned once, before any cross-pod fan-out;
+// append claims it in the Kv first (SET NX), so appending the same id twice stores it once.
+import { randomBytes } from "node:crypto"
+import type { Clock, EventLog, Kv } from "../backend/types"
+import type { LiveStatus } from "../registry"
+import { partyKey } from "./envelope"
+import type { Launch } from "./launch-store"
+import { addressOf, type Message } from "./messages"
+
+export const AGENT_EVENTS_MAX = 10_000
+export const AGENT_EVENTS_AGE_MS = 86_400_000
+/** Record format version (readers reject others rather than skip them). */
+export const AGENT_EVENT_VERSION = 1
+
+/** The scope family a reader needs: sessions:read, sessions:manage, messages:read, sessions:launch. */
+export type EventFamily = "session" | "manage" | "message" | "launch"
+
+export type EventSubject = Readonly<Record<string, string>>
+export type EventData = Readonly<Record<string, string | number | boolean>>
+
+/** An event as readers receive it. */
+export interface AgentEvent {
+  readonly id: string
+  readonly at: number
+  readonly type: string
+  readonly subject: EventSubject
+  readonly data: EventData
+}
+
+/** Who else may read an event beyond the user: the party keys of a message, who started a launch. */
+export interface EventAudience {
+  readonly parties?: readonly string[]
+  readonly by?: string
+}
+
+/** What a writer appends. */
+export interface EventInput {
+  /** A stable id (assigned before fan-out); a new one when absent. */
+  readonly id?: string
+  readonly type: string
+  readonly family: EventFamily
+  readonly subject: EventSubject
+  readonly data: EventData
+  readonly audience?: EventAudience
+}
+
+/** A journal record: the event, its reader-only scope fields, and its position in the user's log. */
+export interface EventRecord {
+  readonly position: string
+  readonly event: AgentEvent
+  readonly family: EventFamily
+  readonly audience?: EventAudience
+}
+
+/** Records after a position, or `reset` when the journal no longer covers it (expired, trimmed, restarted). */
+export type EventsSince = { readonly records: EventRecord[] } | { readonly reset: true }
+
+const FAMILIES: ReadonlySet<string> = new Set<EventFamily>(["session", "manage", "message", "launch"])
+const EVENT_ID = /^evt_[0-9a-f]{20}$/
+
+export const newEventID = (): string => `evt_${randomBytes(10).toString("hex")}`
+
+export interface AgentEventsOptions {
+  readonly log: EventLog
+  readonly kv: Kv
+  readonly now?: Clock
+  readonly onAppend?: (userID: string, record: Pick<EventRecord, "event" | "family" | "audience">) => void | Promise<void>
+}
+
+export class AgentEvents {
+  private readonly log: EventLog
+  private readonly kv: Kv
+  private readonly now: Clock
+  private readonly onAppend?: AgentEventsOptions["onAppend"]
+  /** Readers waiting for this process's next append, per user (long polling; other pods' appends are rechecked). */
+  private readonly waiters = new Map<string, Set<() => void>>()
+
+  constructor(options: AgentEventsOptions) {
+    this.log = options.log
+    this.kv = options.kv
+    this.now = options.now ?? Date.now
+    this.onAppend = options.onAppend
+  }
+
+  /** Stores an event once per id; returns its id. */
+  async append(userID: string, input: EventInput): Promise<string> {
+    const id = input.id ?? newEventID()
+    if (!EVENT_ID.test(id)) throw new Error("Invalid event id")
+    const claim = `aev:${userID}:${id}`
+    if (!(await this.kv.set(claim, "1", { nx: true, px: AGENT_EVENTS_AGE_MS }))) return id
+    const record = {
+      type: input.type,
+      v: AGENT_EVENT_VERSION,
+      id,
+      at: this.now(),
+      family: input.family,
+      subject: input.subject,
+      data: input.data,
+      ...(input.audience ? { audience: input.audience } : {}),
+    }
+    try {
+      await this.log.append(userID, record)
+    } catch (cause) {
+      // Not stored: a retry with the same id must be able to store it.
+      await this.kv.del(claim).catch(() => {})
+      throw cause
+    }
+    await this.onAppend?.(userID, {
+      event: { id, at: record.at, type: input.type, subject: input.subject, data: input.data },
+      family: input.family,
+      ...(input.audience ? { audience: input.audience } : {}),
+    })
+    const waiting = this.waiters.get(userID)
+    if (waiting) for (const wake of [...waiting]) wake()
+    return id
+  }
+
+  /** Resolves on this process's next append for the user, after `ms`, or when `signal` aborts. */
+  appended(userID: string, ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      let set = this.waiters.get(userID)
+      if (!set) this.waiters.set(userID, (set = new Set()))
+      const done = () => {
+        clearTimeout(timer)
+        signal?.removeEventListener("abort", done)
+        set!.delete(done)
+        if (set!.size === 0 && this.waiters.get(userID) === set) this.waiters.delete(userID)
+        resolve()
+      }
+      const timer = setTimeout(done, ms)
+      set.add(done)
+      if (signal?.aborted) done()
+      else signal?.addEventListener("abort", done, { once: true })
+    })
+  }
+
+  /** The position of the user's latest record; a reader holding it gets every later one. */
+  latest(userID: string): Promise<string> {
+    return this.log.latest(userID)
+  }
+
+  async since(userID: string, position: string): Promise<EventsSince> {
+    const result = await this.log.since(userID, position)
+    if ("resync" in result) return { reset: true }
+    const records: EventRecord[] = []
+    for (const logged of result.events) {
+      const m = logged.message as Record<string, unknown>
+      // A record this version cannot read is a reset, never a silent skip.
+      if (m.v !== AGENT_EVENT_VERSION || typeof m.id !== "string" || typeof m.at !== "number" || !FAMILIES.has(m.family as string)) return { reset: true }
+      records.push({
+        position: logged.id,
+        event: { id: m.id, at: m.at, type: String(m.type), subject: (m.subject ?? {}) as EventSubject, data: (m.data ?? {}) as EventData },
+        family: m.family as EventFamily,
+        ...(m.audience ? { audience: m.audience as EventAudience } : {}),
+      })
+    }
+    return { records }
+  }
+}
+
+// ---- Compact builders (allowlists) ------------------------------------------------------------------------
+
+/** A stored agent message changed (sent, delivered, answered…): never its text. */
+export function messageEvent(message: Message): EventInput {
+  const { id, kind, state, from, recipient, replyTo, delivery } = message
+  return {
+    type: "message.changed",
+    family: "message",
+    subject: {
+      messageID: id,
+      ...(recipient.kind === "session" ? { sessionID: recipient.sessionID } : {}),
+      ...(from.kind === "session" ? { senderID: from.sessionID } : {}),
+    },
+    data: { kind, state, from: addressOf(from), to: message.to, ...(replyTo ? { replyTo } : {}), ...(delivery ? { delivery } : {}) },
+    audience: { parties: [partyKey(from), partyKey(recipient)] },
+  }
+}
+
+/** A launch changed: never its prompt, reason or labels. */
+export function launchEvent(launch: Launch): EventInput {
+  return {
+    type: "launch.changed",
+    family: "launch",
+    subject: { launchID: launch.id, ...(launch.sessionID !== undefined ? { sessionID: launch.sessionID } : {}) },
+    data: { state: launch.state, ...(launch.outcome !== undefined ? { outcome: launch.outcome } : {}), ...(launch.name !== undefined ? { name: launch.name } : {}) },
+    ...(launch.by !== undefined ? { audience: { by: launch.by } } : {}),
+  }
+}
+
+/** A session's archive state changed. */
+export const archiveEvent = (sessionID: string, archived: boolean): EventInput => ({ type: "session.archived", family: "manage", subject: { sessionID }, data: { archived } })
+
+export const pinnedEvent = (sessionID: string, pinned: boolean): EventInput => ({ type: "session.pinned", family: "manage", subject: { sessionID }, data: { pinned } })
+
+/** A session was explicitly named (names are validated slugs: a-z, 0-9 and -). */
+export const namedEvent = (sessionID: string, name: string): EventInput => ({ type: "session.named", family: "manage", subject: { sessionID }, data: { name } })
+
+/** A session claimed (held) or released a role; role and project are validated slugs. */
+export function roleEvent(sessionID: string, held: boolean, role: { role: string; project?: string; generation?: number; exclusive?: boolean }): EventInput {
+  return {
+    type: held ? "role.claimed" : "role.released",
+    family: "manage",
+    subject: { sessionID },
+    data: {
+      role: role.role,
+      ...(role.project !== undefined ? { project: role.project } : {}),
+      ...(held && role.generation !== undefined ? { generation: role.generation } : {}),
+      ...(held && role.exclusive ? { exclusive: true } : {}),
+    },
+  }
+}
+
+interface Known {
+  state: string
+  blockers: Set<string>
+}
+
+/**
+ * State and blocker changes of status trees, against what was seen before (one per writer). Bounded by the live
+ * trees: a tree's entry is replaced by each status of it and dropped by forget().
+ */
+export class StatusDiff {
+  private readonly trees = new Map<string, Map<string, Known>>()
+
+  events(rootID: string, sessions: readonly LiveStatus[]): EventInput[] {
+    const before = this.trees.get(rootID) ?? new Map<string, Known>()
+    const after = new Map<string, Known>()
+    const out: EventInput[] = []
+    for (const entry of sessions) {
+      const known = before.get(entry.id)
+      const subject = { sessionID: entry.id, rootID }
+      const open = new Set(entry.blockers.map((b) => b.id))
+      for (const b of entry.blockers) if (!known?.blockers.has(b.id)) out.push({ type: "blocker.opened", family: "session", subject, data: { blockerID: b.id, kind: b.kind } })
+      for (const id of known?.blockers ?? []) if (!open.has(id)) out.push({ type: "blocker.closed", family: "session", subject, data: { blockerID: id } })
+      if (known?.state !== entry.state) out.push({ type: "session.changed", family: "session", subject, data: { state: entry.state, ...(known ? { prev: known.state } : {}) } })
+      after.set(entry.id, { state: entry.state, blockers: open })
+    }
+    this.trees.set(rootID, after)
+    return out
+  }
+
+  /** Drops a tree that is gone. */
+  forget(rootID: string): void {
+    this.trees.delete(rootID)
+  }
+
+  roots(): string[] {
+    return [...this.trees.keys()]
+  }
+}
+
+/** Presence per user (sessions and machines) diffed against the previous view (the catalog writer's). */
+export interface PresenceView {
+  readonly sessions: ReadonlySet<string>
+  /** Machine id → name, for the machines with a connected process. */
+  readonly machines: ReadonlyMap<string, string>
+}
+
+export function presenceEvents(before: PresenceView, after: PresenceView): EventInput[] {
+  const out: EventInput[] = []
+  for (const id of after.sessions) if (!before.sessions.has(id)) out.push({ type: "session.added", family: "session", subject: { sessionID: id }, data: {} })
+  for (const id of before.sessions) if (!after.sessions.has(id)) out.push({ type: "session.removed", family: "session", subject: { sessionID: id }, data: {} })
+  for (const [id, name] of after.machines) if (!before.machines.has(id)) out.push({ type: "machine.changed", family: "session", subject: { machineID: id }, data: { name, online: true } })
+  for (const [id, name] of before.machines) if (!after.machines.has(id)) out.push({ type: "machine.changed", family: "session", subject: { machineID: id }, data: { name, online: false } })
+  return out
+}

package/src/central/agent/grant-requests.ts

@@ -0,0 +1,221 @@
+// Grant requests (design §5, §7; P3-T9): an agent asks the user for a grant. Grants are created only by users
+// (grant-routes.ts); a session (any token) or an app token (scope messages:send) may only request one, and the
+// user's tap in the console creates it.
+//
+// - The body is {grant, why}: the grant as POST /api/agent/grants takes it, validated the same way (validateGrant)
+//   when requested and again, as the user's, when approved (Grants.create). The holder defaults to the requester
+//   (`ses_…`, `app:<token id>`); it may name only the requester itself (`ses_…`, its `@name`: stored as the session
+//   id, so a name moving on never moves the grant) or a reserved `@@role` the requesting session holds now.
+//   Another session or app is forbidden; a session that is not the user's is not_found.
+// - It opens a Decision to @me (tap tier, high urgency; options approve / deny, deny safe) whose question
+//   summarises holder, projects, verbs, permissions allow/never, always, the hourly cap, expiry and the why
+//   (sanitised); its action (kind "grant", the canonical grant body) is the hub's, never the asker's.
+// - Approve: the grant is created AS THE USER (owner the user); the requester's reply carries the grant id. The
+//   holder gone by then (not_found) closes the Decision instead. Deny: nothing is created; the reply says so.
+//   No editing on approval (yet): the user may create an edited grant directly and deny the request.
+// - Limits: one open request per requester (another is rate_limited with the open Decision's id; a version-checked
+//   reservation settles races) and GRANT_REQUESTS_PER_HOUR per requester an hour (Counters). Asks to @me also
+//   count against the message limits.
+// - Audit: the request (grant.request, needs_user, escalated) and its outcome (grant.approve ok / grant.deny
+//   refused, as the user).
+import type { Counters, StateStore } from "../backend/types"
+import type { AgentActor, AppActor, SessionActor, UserActor } from "./actor"
+import type { AgentAudit } from "./audit"
+import { type ActOutcome, type Decision, type Decisions, WHY_MAX } from "./decisions"
+import type { Directory } from "./directory"
+import { type Party, partyFromActor, partyKey, partyLabel, sanitizeLabel } from "./envelope"
+import { AgentError } from "./errors"
+import type { Grants } from "./grants"
+import type { Message } from "./messages"
+import { parseAddress } from "./names"
+import { type GrantSpec, validateGrant } from "./policy"
+
+/** Grant requests each requester opens an hour. */
+export const GRANT_REQUESTS_PER_HOUR = 5
+/** Characters of the question (lists are cut to fit). */
+const QUESTION_MAX = 4_000
+/** A reservation older than this (its opener crashed) no longer blocks a new request. */
+const RESERVATION_MS = 60_000
+const HOUR_MS = 3_600_000
+const COLLECTION = "grant-requests"
+const BODY_FIELDS = ["grant", "why"]
+
+/** requester → its latest request's Decision (without decisionID while it is being opened). */
+interface RequestRecord {
+  readonly at: number
+  readonly decisionID?: string
+}
+
+export interface GrantRequestsDeps {
+  readonly state: StateStore
+  readonly counters: Counters
+  readonly decisions: Pick<Decisions, "ask" | "get">
+  readonly grants: Pick<Grants, "create">
+  readonly directory: Pick<Directory, "resolve">
+  readonly audit?: Pick<AgentAudit, "record">
+  /** The requester as envelopes name it; default: from the actor alone. */
+  readonly describe?: (userID: string, actor: AgentActor) => Party
+  /** The Decision's ask was stored (the console's message feed). */
+  readonly published?: (userID: string, message: Message) => void
+  readonly now?: () => number
+}
+
+const invalid = (message: string) => new AgentError("invalid", message)
+const forbidden = (message: string) => new AgentError("forbidden", message, { hint: "Request a grant held by yourself (the default), or by a reserved role you hold" })
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+
+export class GrantRequests {
+  private readonly now: () => number
+
+  constructor(private readonly deps: GrantRequestsDeps) {
+    this.now = deps.now ?? Date.now
+    this.act = this.act.bind(this)
+  }
+
+  /** Opens the Decision for the agent's request. Throws invalid, forbidden, not_found or rate_limited. */
+  async request(userID: string, actor: AgentActor, body: unknown): Promise<{ decision: Decision; message: Message }> {
+    if (actor.kind === "user") throw invalid("You are the user: create the grant directly (POST /api/agent/grants)")
+    if (!isObject(body)) throw invalid("A grant request is {grant, why}")
+    for (const key of Object.keys(body)) if (!BODY_FIELDS.includes(key)) throw invalid(`Unknown grant request field ${key}`)
+    if (!isObject(body.grant)) throw invalid("grant is the grant to request (as POST /api/agent/grants takes it)")
+    const why = typeof body.why === "string" && body.why.length <= WHY_MAX * 4 ? sanitizeLabel(body.why, WHY_MAX) : ""
+    if (!why) throw invalid(`why is the reason the user reads (1–${WHY_MAX} characters)`)
+    const own = ownHolder(actor)
+    const spec = validateGrant({ ...body.grant, holder: body.grant.holder ?? own })
+    const holder = this.holder(userID, actor, spec.holder, own)
+    const grant = canonical({ ...spec, holder })
+
+    const requester = this.describe(userID, actor)
+    const key = partyKey(requester)
+    const { state, counters, decisions } = this.deps
+    const existing = await state.get<RequestRecord>(userID, COLLECTION, key)
+    if (existing?.value.decisionID) {
+      const open = await decisions.get(userID, existing.value.decisionID)
+      if (open?.state === "open") {
+        throw new AgentError("rate_limited", `Your grant request ${open.id} still waits for the user`, { extra: { retryAfter: 60, decisionID: open.id } })
+      }
+    } else if (existing && this.now() - existing.value.at < RESERVATION_MS) {
+      throw new AgentError("rate_limited", "Your grant request is being opened", { extra: { retryAfter: 1 } })
+    }
+    const at = this.now()
+    const count = await counters.incr(`grant-requests:${userID}:${key}`, HOUR_MS)
+    if (count > GRANT_REQUESTS_PER_HOUR) {
+      throw new AgentError("rate_limited", `At most ${GRANT_REQUESTS_PER_HOUR} grant requests an hour`, { extra: { retryAfter: HOUR_MS / 1000 } })
+    }
+    const reserved = await state.put(userID, COLLECTION, key, { at } satisfies RequestRecord, { ifVersion: existing?.version ?? 0 })
+    if (!reserved.ok) throw new AgentError("rate_limited", "Your grant request is being opened", { extra: { retryAfter: 1 } })
+    let opened: { decision: Decision; message: Message }
+    try {
+      opened = await decisions.ask(
+        userID,
+        actor,
+        {
+          question: question(partyLabel(requester), spec, holder, why),
+          options: [
+            { id: "approve", label: "Approve grant" },
+            { id: "deny", label: "Deny", safe: true },
+          ],
+          urgency: "high",
+          tier: "tap",
+        },
+        { action: { kind: "grant", requester: key, grant } },
+      )
+    } catch (cause) {
+      await state.delete(userID, COLLECTION, key, { ifVersion: reserved.version })
+      throw cause
+    }
+    await state.put(userID, COLLECTION, key, { at, decisionID: opened.decision.id } satisfies RequestRecord, { ifVersion: reserved.version })
+    this.deps.published?.(userID, opened.message)
+    await this.deps.audit?.record(userID, { actor: requester, verb: "grant.request", target: target(actor), decision: "needs_user", reason: why, outcome: "escalated" })
+    return opened
+  }
+
+  /** Decisions' action runner: approve creates the grant as the answering user; deny creates nothing. */
+  async act(userID: string, decision: Decision, choice: { readonly option?: string }, by: UserActor): Promise<ActOutcome> {
+    const action = decision.action
+    if (!action || action.kind !== "grant" || by.userID !== userID) return "gone"
+    const about = decision.from.kind === "session" ? { sessionID: decision.from.sessionID } : {}
+    const reason = `Decision ${decision.id}`
+    if (choice.option !== "approve") {
+      await this.deps.audit?.record(userID, { actor: { kind: "user" }, verb: "grant.deny", target: about, decision: "allow", reason, outcome: "refused" })
+      return "done"
+    }
+    let created
+    try {
+      created = await this.deps.grants.create(userID, action.grant)
+    } catch (cause) {
+      if (!(cause instanceof AgentError) || cause.code !== "not_found") throw cause
+      await this.deps.audit?.record(userID, { actor: { kind: "user" }, verb: "grant.approve", target: about, decision: "allow", reason, outcome: "gone" })
+      return { outcome: "gone", reason: "The requested holder is gone" }
+    }
+    await this.deps.audit?.record(userID, { actor: { kind: "user" }, verb: "grant.approve", target: about, grant: created.id, decision: "allow", reason, outcome: "ok" })
+    return { outcome: "done", note: `Grant ${created.id} created (holder ${created.holder}, until ${new Date(created.expiresAt).toISOString()})` }
+  }
+
+  // ---- internals ----------------------------------------------------------------------------------------
+
+  private describe(userID: string, actor: AgentActor): Party {
+    return this.deps.describe?.(userID, actor) ?? partyFromActor(actor)
+  }
+
+  /** The holder the request may name (see the header), as stored. */
+  private holder(userID: string, actor: SessionActor | AppActor, holder: string, own: string): string {
+    if (holder === own) return own
+    if (holder.startsWith("app:") || actor.kind === "app") throw forbidden("A grant request may name only the requester as its holder")
+    const holds = (sessions: readonly { readonly sessionID: string }[]) => sessions.some((s) => s.sessionID === actor.sessionID)
+    if (parseAddress(holder)?.kind === "role") {
+      let held = false
+      try {
+        held = holds(this.deps.directory.resolve(userID, holder).sessions)
+      } catch {
+        held = false
+      }
+      if (!held) throw forbidden(`You do not hold ${holder}`)
+      return holder
+    }
+    // A session or name that is not the user's is not_found (the resolver's tenancy).
+    const { sessions } = this.deps.directory.resolve(userID, holder)
+    if (sessions.length !== 1 || !holds(sessions)) throw forbidden("A grant request may name only the requester as its holder")
+    return actor.sessionID
+  }
+}
+
+/** The holder a request defaults to: the session's id, or `app:<token id>`. */
+const ownHolder = (actor: SessionActor | AppActor): string => (actor.kind === "session" ? actor.sessionID : `app:${actor.tokenID}`)
+
+const target = (actor: SessionActor | AppActor) => (actor.kind === "session" ? { sessionID: actor.sessionID } : {})
+
+/** The spec as the body Grants.create takes (expires in seconds). */
+const canonical = (spec: GrantSpec): Record<string, unknown> => ({
+  holder: spec.holder,
+  scope: { projects: [...spec.scope.projects] },
+  allow: [...spec.allow],
+  permissions: { allow: [...spec.permissions.allow], never: [...spec.permissions.never] },
+  allowAlways: spec.allowAlways,
+  maxActionsPerHour: spec.maxActionsPerHour,
+  expires: Math.round(spec.expiresInMs / 1000),
+})
+
+/** `90m`, `8h`, `2d`; seconds otherwise. */
+function duration(ms: number): string {
+  for (const [unit, size] of [["d", 86_400_000], ["h", 3_600_000], ["m", 60_000]] as const) if (ms % size === 0) return `${ms / size}${unit}`
+  return `${Math.round(ms / 1000)}s`
+}
+
+/** "@orchestrator requests a grant: holder ses_o; projects /p; verbs approve, deny; …. Why: …" (bounded). */
+function question(by: string, spec: GrantSpec, holder: string, why: string): string {
+  const list = (values: readonly string[]) => (values.length ? values.join(", ") : "none")
+  const text = [
+    `${by} requests a grant: holder ${holder}`,
+    `projects ${list(spec.scope.projects)}`,
+    `verbs ${list(spec.allow)}`,
+    `permissions allow ${list(spec.permissions.allow)}`,
+    `never ${list(spec.permissions.never)}`,
+    `always ${spec.allowAlways ? "yes" : "no"}`,
+    `up to ${spec.maxActionsPerHour} actions an hour`,
+    `expires ${duration(spec.expiresInMs)} after approval`,
+  ].join("; ")
+  const tail = `. Why: ${why}`
+  const head = text.length + tail.length > QUESTION_MAX ? `${text.slice(0, Math.max(0, QUESTION_MAX - tail.length - 1))}…` : text
+  return `${head}${tail}`
+}

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

@@ -0,0 +1,70 @@
+// /api/agent/grants (design §5, §7): the user's grants. User actors only (allow {}): the device cookie (same-origin
+// writes, checked by the agent framework) or a device token. A session or app token never creates, edits, reads
+// or revokes a grant (escalation guard). Answers {grant} / {grants}, never cached; the owner is not echoed.
+//
+//   POST   /api/agent/grants       create (201)          GET /api/agent/grants      list, newest first
+//   GET    /api/agent/grants/:id   one grant             PUT /api/agent/grants/:id  replace (holder fixed)
+//   DELETE /api/agent/grants/:id   revoke (gone when already ended)
+//
+// Agents only request one (grant-requests.ts): POST /api/agent/grants/requests {grant, why} from a session (any of
+// its tokens) or an app token with messages:send → 201 {message, decision} (a tap Decision for the user); the user
+// gets invalid (create it directly).
+import type { GrantRequests } from "./grant-requests"
+import { type Grant, type Grants, grantState } from "./grants"
+import type { AgentRoute } from "./routes"
+
+// A literal: routes.ts imports this module (AGENT_PREFIX is not initialised yet when it loads).
+const PREFIX = "/api/agent/grants"
+const NO_STORE = { "cache-control": "no-store" }
+
+/** A grant as the API shows it: without the owner, with its state now. */
+export function grantView(grant: Grant, at: number) {
+  const { owner: _owner, ...rest } = grant
+  return { ...rest, state: grantState(grant, at) }
+}
+
+export function grantRoutes(grants: Grants, now: () => number = Date.now, requests?: GrantRequests): AgentRoute[] {
+  const one = (grant: Grant, status = 200) => Response.json({ grant: grantView(grant, now()) }, { status, headers: NO_STORE })
+  return [
+    ...(requests
+      ? [
+          {
+            method: "POST",
+            path: `${PREFIX}/requests`,
+            allow: { session: true, scope: "messages:send" },
+            handle: async ({ request, actor, user }) => Response.json(await requests.request(user.id, actor, await request.json()), { status: 201, headers: NO_STORE }),
+          } satisfies AgentRoute,
+        ]
+      : []),
+    {
+      method: "POST",
+      path: PREFIX,
+      allow: {},
+      handle: async ({ request, user }) => one(await grants.create(user.id, await request.json()), 201),
+    },
+    {
+      method: "GET",
+      path: PREFIX,
+      allow: {},
+      handle: async ({ user }) => Response.json({ grants: (await grants.list(user.id)).map((g) => grantView(g, now())) }, { headers: NO_STORE }),
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id`,
+      allow: {},
+      handle: async ({ params, user }) => one(await grants.get(user.id, params.id!)),
+    },
+    {
+      method: "PUT",
+      path: `${PREFIX}/:id`,
+      allow: {},
+      handle: async ({ params, request, user }) => one(await grants.update(user.id, params.id!, await request.json())),
+    },
+    {
+      method: "DELETE",
+      path: `${PREFIX}/:id`,
+      allow: {},
+      handle: async ({ params, user }) => one(await grants.revoke(user.id, params.id!)),
+    },
+  ]
+}