@huynle/hub 0.6.0 → 0.7.1

package/src/central/agent/envelope.ts

@@ -0,0 +1,51 @@
+// The message envelope (design §3.3): the pure renderer and sanitiser live in the SDK (packages/sdk/src/envelope.ts,
+// shared with the plugin's hub tool and `hub mcp`) and are re-exported here; the hub adds the sender derived only
+// from the authenticated actor (partyFromActor) and the party keys of its indexes.
+import type { Party } from "../../../packages/sdk/src/types.ts"
+import { sanitizeLabel } from "../../../packages/sdk/src/envelope.ts"
+import type { AgentActor } from "./actor"
+
+export { LABEL_MAX, partyLabel, renderEnvelope, renderPrimer, sanitizeLabel, sanitizeText, type EnvelopeInput, type EnvelopeKind } from "../../../packages/sdk/src/envelope.ts"
+export type { Party } from "../../../packages/sdk/src/types.ts"
+
+/** Directory facts for a session sender's label (never taken from a request body). */
+export interface PartyInfo {
+  readonly name?: string
+  readonly harness?: string
+  readonly machine?: string
+}
+
+/** The sender of a request, from its actor; session labels come from the hub's directory, sanitised. */
+export function partyFromActor(actor: AgentActor, info: PartyInfo = {}): Party {
+  switch (actor.kind) {
+    case "user":
+      return { kind: "user" }
+    case "app":
+      return { kind: "app", tokenID: actor.tokenID, ...labels({ label: actor.label }) }
+    case "session":
+      return { kind: "session", sessionID: actor.sessionID, ...labels({ name: info.name, harness: info.harness, machine: info.machine }) }
+  }
+}
+
+/** The given labels, sanitised, without empty ones. */
+function labels<T extends Record<string, string | undefined>>(values: T): Partial<Record<keyof T, string>> {
+  const out: Partial<Record<keyof T, string>> = {}
+  for (const [key, value] of Object.entries(values) as [keyof T, string | undefined][]) {
+    const clean = value === undefined ? "" : sanitizeLabel(value)
+    if (clean) out[key] = clean
+  }
+  return out
+}
+
+/** A stable key per party (index and mute keys): `ses:<id>`, `user`, `app:<tokenID>`. */
+export function partyKey(party: Party): string {
+  switch (party.kind) {
+    case "session":
+      return `ses:${party.sessionID}`
+    case "user":
+      return "user"
+    case "app":
+      return `app:${party.tokenID}`
+  }
+}
+

package/src/central/agent/errors.ts

@@ -0,0 +1,72 @@
+// The /api/agent error envelope (design §8, §14.5): {error: {code, message, hint?, ...extra}}. Only /api/agent/*
+// answers this way; the console routes keep their {error: string, code?} envelope (the web app reads it).
+
+/** HTTP status of each agent error code. */
+export const AGENT_ERROR_STATUS = {
+  /** Malformed request (bad JSON, bad fields, cookie and bearer together). */
+  invalid: 400,
+  /** No credential, or an unknown, revoked or disabled one. */
+  unauthorized: 401,
+  /** A session or app token that expired: get a new one. */
+  token_expired: 401,
+  /** Outside the grant; a recommendation was recorded for the user. */
+  needs_user: 403,
+  /** No grant or scope, or a credential not admitted on this route. */
+  forbidden: 403,
+  /** No such thing, or another user's (they answer alike). */
+  not_found: 404,
+  /** The address matches several sessions (`candidates`). */
+  ambiguous: 409,
+  /** Explicit name or exclusive role already held. */
+  name_taken: 409,
+  /** Already answered, expired or ended. */
+  gone: 410,
+  /** The spoke or node lacks the feature or runtime (`feature`, `harness`). */
+  unsupported: 422,
+  /** A kill switch is on. */
+  paused: 423,
+  /** A pair, recipient, user or launch cap (`retryAfter`, seconds). */
+  rate_limited: 429,
+  /** An unexpected failure (details are logged, not sent). */
+  internal: 500,
+  /** The machine is offline (actions only; messages queue instead). */
+  offline: 503,
+} as const satisfies Record<string, number>
+
+export type AgentErrorCode = keyof typeof AGENT_ERROR_STATUS
+
+export interface AgentErrorOptions {
+  readonly hint?: string
+  /** More fields in the envelope, e.g. candidates, retryAfter, feature; never code or message. */
+  readonly extra?: Record<string, unknown>
+}
+
+/** Throw from an agent handler; answered as the envelope with the code's status. */
+export class AgentError extends Error {
+  constructor(
+    readonly code: AgentErrorCode,
+    message: string,
+    readonly options: AgentErrorOptions = {},
+  ) {
+    super(message)
+  }
+}
+
+export function agentError(error: AgentError): Response {
+  const { hint, extra = {} } = error.options
+  const headers: Record<string, string> = { "cache-control": "no-store" }
+  const retryAfter = extra.retryAfter
+  if (typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter >= 0) headers["retry-after"] = String(Math.ceil(retryAfter))
+  return Response.json(
+    { error: { ...extra, code: error.code, message: error.message, ...(hint ? { hint } : {}) } },
+    { status: AGENT_ERROR_STATUS[error.code], headers },
+  )
+}
+
+/** The envelope for anything an agent handler threw. */
+export function agentFailure(cause: unknown): Response {
+  if (cause instanceof AgentError) return agentError(cause)
+  if (cause instanceof SyntaxError) return agentError(new AgentError("invalid", "Invalid JSON"))
+  console.error("[hub] agent request failed:", cause)
+  return agentError(new AgentError("internal", "Internal error"))
+}

package/src/central/agent/escalation.ts

@@ -0,0 +1,219 @@
+// Escalations (design §5, §12.1; decision wvqeuis0 §7; exploration hcw63slg Security): what the acting engine's
+// needs_user becomes. An agent asked to approve a permission request outside its grant; the user decides.
+//
+// - ONE Decision per (holder, request): the first escalation opens it (options approve [always] / deny (safe), the
+//   agent's recommendation, the tier the hub set on the evaluation, about the asking session); escalating the same
+//   request again updates the open Decision's reason instead (no new push). Concurrent escalations race on a
+//   version-checked reservation: one opens the Decision, the other is rate_limited (retry).
+// - The recommendation also shows on the request's blocker (registry.recommend: catalog, status, the push's
+//   service worker reads it there).
+// - Answering (decisions.ts runs `act` after the answer wins) replies to the permission AS THE USER through the
+//   shared executor: no grant, no kill switch (those bind agents, not the user); tenancy of the tree is checked
+//   again; the reply is in the agent audit as the user's. The request gone → the Decision closes (gone); its spoke
+//   not serving permission → it closes with the unsupported reason (audited unsupported).
+// - The request answered elsewhere, or ended (registry.onPermissionClosed → closed()): every Decision escalating
+//   it closes.
+// - Spam limits: ESCALATIONS_PER_HOLDER_HOUR new Decisions per holder an hour, ESCALATIONS_OPEN_MAX open ones per
+//   user (both rate_limited: the needs_user still stands, without a Decision), and pushes coalesce: a Decision
+//   opened within ESCALATION_PUSH_COALESCE_MS of the user's last escalation push opens quietly (still listed and
+//   live in the console).
+import { type Actions, unsupportedMessage } from "../actions"
+import type { Counters, StateStore } from "../backend/types"
+import type { Registry } from "../registry"
+import type { PermissionDecision } from "../../protocol"
+import type { BlockerRecommendation } from "../../status"
+import type { Escalation } from "./acting"
+import type { AgentActor, UserActor } from "./actor"
+import type { AgentAudit } from "./audit"
+import { type ActOutcome, type Decision, type DecisionActor, type Decisions, WHY_MAX } from "./decisions"
+import { type Party, partyFromActor, partyKey, partyLabel } from "./envelope"
+import { AgentError } from "./errors"
+import type { Message } from "./messages"
+
+/** New escalation Decisions a holder opens an hour (their asks to @me also count in its message pair limit). */
+export const ESCALATIONS_PER_HOLDER_HOUR = 20
+/** Open escalation Decisions per user. */
+export const ESCALATIONS_OPEN_MAX = 20
+/** Escalations opened this soon after the user's last escalation push do not push again. */
+export const ESCALATION_PUSH_COALESCE_MS = 60_000
+/** A reservation older than this (its opener crashed) no longer blocks a new escalation. */
+const RESERVATION_MS = 60_000
+const HOUR_MS = 3_600_000
+/** Characters of the question (the request's resources are listed up to it). */
+const QUESTION_MAX = 2_000
+const CLOSED_REASON = "The request was answered elsewhere or ended"
+
+const COLLECTION = "escalations"
+
+/** (holder, request) → its Decision; without decisionID while it is being opened. */
+interface EscalationRecord {
+  readonly holder: string
+  readonly requestID: string
+  readonly at: number
+  readonly decisionID?: string
+}
+
+export interface EscalationsDeps {
+  readonly state: StateStore
+  readonly counters: Counters
+  readonly decisions: Pick<Decisions, "ask" | "get" | "list" | "close" | "revise">
+  readonly registry: Pick<Registry, "recommend" | "sessionTenant">
+  readonly actions: Pick<Actions, "answerPermission">
+  readonly audit?: Pick<AgentAudit, "record">
+  /** The holder as envelopes name it (a session by its directory name); 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 rateLimited = (message: string, retryAfter: number) => new AgentError("rate_limited", message, { extra: { retryAfter } })
+
+export class Escalations {
+  private readonly now: () => number
+
+  constructor(private readonly deps: EscalationsDeps) {
+    this.now = deps.now ?? Date.now
+    this.act = this.act.bind(this)
+  }
+
+  /** The acting engine's escalate hook: opens or updates the holder's Decision about the request. */
+  async escalate(escalation: Escalation): Promise<{ decisionID?: string }> {
+    const { userID } = escalation
+    const holder = this.describe(userID, escalation.actor)
+    const key = `${partyKey(holder)} ${escalation.requestID}`
+    const { state } = this.deps
+    const existing = await state.get<EscalationRecord>(userID, COLLECTION, key)
+    if (existing?.value.decisionID) {
+      const decision = await this.deps.decisions.get(userID, existing.value.decisionID)
+      if (decision?.state === "open") return this.update(escalation, holder, decision)
+    } else if (existing && this.now() - existing.value.at < RESERVATION_MS) {
+      throw rateLimited("An escalation of this request is being opened", 1)
+    }
+    const record: EscalationRecord = { holder: partyKey(holder), requestID: escalation.requestID, at: this.now() }
+    const reserved = await state.put(userID, COLLECTION, key, record, { ifVersion: existing?.version ?? 0 })
+    if (!reserved.ok) throw rateLimited("An escalation of this request is being opened", 1)
+    try {
+      const decision = await this.open(escalation, holder)
+      await state.put(userID, COLLECTION, key, { ...record, decisionID: decision.id }, { ifVersion: reserved.version })
+      return { decisionID: decision.id }
+    } catch (cause) {
+      await state.delete(userID, COLLECTION, key, { ifVersion: reserved.version })
+      throw cause
+    }
+  }
+
+  /** Decisions' action runner: replies to the escalated permission as the answering user. */
+  async act(userID: string, decision: Decision, choice: { readonly option?: string }, by: UserActor): Promise<ActOutcome> {
+    const action = decision.action
+    if (!action || action.kind !== "permission") return "gone"
+    const reply: PermissionDecision = choice.option === "always" ? "always" : choice.option === "approve" ? "once" : "reject"
+    const verb = reply === "reject" ? "deny" : "approve"
+    const owned = this.deps.registry.sessionTenant(action.rootID) === by.userID && by.userID === userID
+    const answered = owned ? await this.deps.actions.answerPermission({ rootID: action.rootID, requestID: action.requestID, decision: reply }) : { outcome: "gone" as const }
+    await this.deps.audit?.record(userID, {
+      actor: { kind: "user" },
+      verb,
+      target: { sessionID: action.sessionID, requestID: action.requestID },
+      decision: "allow",
+      reason: `Decision ${decision.id}`,
+      outcome: answered.outcome === "done" ? "ok" : answered.outcome,
+    })
+    await this.forget(userID, action.requestID)
+    // The spoke holding the request cannot answer permissions: the Decision closes saying so (not "answered elsewhere").
+    if (answered.outcome === "unsupported") return { outcome: "gone", reason: unsupportedMessage(answered) }
+    return answered.outcome === "done" ? "done" : "gone"
+  }
+
+  /** The request went away (answered elsewhere, ended): closes every Decision escalating it. */
+  async closed(userID: string | undefined, requestID: string): Promise<void> {
+    if (userID === undefined) return
+    for (const { key, value } of await this.deps.state.list<EscalationRecord>(userID, COLLECTION)) {
+      if (value.requestID !== requestID) continue
+      if (value.decisionID) await this.deps.decisions.close(userID, value.decisionID, CLOSED_REASON)
+      await this.deps.state.delete(userID, COLLECTION, key)
+    }
+  }
+
+  // ---- internals ----------------------------------------------------------------------------------------
+
+  private describe(userID: string, actor: AgentActor): Party {
+    return this.deps.describe?.(userID, actor) ?? partyFromActor(actor)
+  }
+
+  /** A new Decision, within the spam limits. */
+  private async open(escalation: Escalation, holder: Party): Promise<Decision> {
+    const { userID } = escalation
+    const { decisions, counters } = this.deps
+    const open = (await decisions.list(userID, { state: "open" })).filter((d) => d.action?.kind === "permission").length
+    if (open >= ESCALATIONS_OPEN_MAX) throw rateLimited(`At most ${ESCALATIONS_OPEN_MAX} escalations wait for the user at once`, 60)
+    const opened = await counters.incr(`escalations:${userID}:${partyKey(holder)}`, HOUR_MS)
+    if (opened > ESCALATIONS_PER_HOLDER_HOUR) throw rateLimited(`At most ${ESCALATIONS_PER_HOLDER_HOUR} escalations an hour`, 3600)
+    const pushes = await counters.incr(`escalation-push:${userID}`, ESCALATION_PUSH_COALESCE_MS)
+    const recommend = escalation.always ? "always" : "approve"
+    const why = boundedWhy(escalation.why)
+    const { message, decision } = await decisions.ask(
+      userID,
+      escalation.actor,
+      {
+        question: question(escalation, partyLabel(holder)),
+        options: [
+          ...(escalation.always ? [{ id: "always", label: "Approve always" }] : []),
+          { id: "approve", label: "Approve once" },
+          { id: "deny", label: "Deny", safe: true },
+        ],
+        recommendation: { option: recommend, ...(why ? { why } : {}) },
+        urgency: "high",
+        tier: escalation.evaluation.tier,
+        about: [escalation.sessionID],
+      },
+      {
+        action: { kind: "permission", requestID: escalation.requestID, rootID: escalation.rootID, sessionID: escalation.sessionID, always: escalation.always },
+        quiet: pushes > 1,
+      },
+    )
+    this.deps.published?.(userID, message)
+    this.showOnBlocker(escalation.requestID, holder, decision)
+    return decision
+  }
+
+  /** The same holder escalated the request again: a new reason replaces the recommendation's. */
+  private async update(escalation: Escalation, holder: Party, decision: Decision): Promise<{ decisionID: string }> {
+    const why = boundedWhy(escalation.why)
+    let current = decision
+    if (why && why !== decision.recommendation?.why) {
+      const option = decision.recommendation?.option ?? (escalation.always ? "always" : "approve")
+      current = (await this.deps.decisions.revise(escalation.userID, decision.id, { recommendation: { option, why } })) ?? decision
+    }
+    this.showOnBlocker(escalation.requestID, holder, current)
+    return { decisionID: decision.id }
+  }
+
+  private showOnBlocker(requestID: string, holder: Party, decision: Decision): void {
+    const why = decision.recommendation?.why
+    const recommendation: BlockerRecommendation = { by: partyLabel(holder), recommends: "approve", ...(why ? { why } : {}), decisionID: decision.id }
+    this.deps.registry.recommend(requestID, recommendation)
+  }
+
+  /** Drops the (holder, request) records of an answered request. */
+  private async forget(userID: string, requestID: string): Promise<void> {
+    for (const { key, value } of await this.deps.state.list<EscalationRecord>(userID, COLLECTION)) {
+      if (value.requestID === requestID) await this.deps.state.delete(userID, COLLECTION, key)
+    }
+  }
+}
+
+/** The agent's reason, cut to what a Decision keeps. */
+function boundedWhy(why: string | undefined): string | undefined {
+  const trimmed = why?.trim()
+  return trimmed ? Array.from(trimmed).slice(0, WHY_MAX).join("") : undefined
+}
+
+/** "@orchestrator asks to approve shell: bun test, bun run lint. Outside its grant: …" (bounded). */
+function question(escalation: Escalation, by: string): string {
+  const { request, evaluation } = escalation
+  const what = request ? `${request.action}${request.resources.length ? `: ${request.resources.join(", ")}` : ""}` : "a permission request (details unknown)"
+  const always = escalation.always && request?.save?.length ? ` always (saves ${request.save.join(", ")})` : escalation.always ? " always" : ""
+  const text = `${by} asks to approve${always} ${what}. Outside its grant: ${evaluation.reason}`
+  return text.length > QUESTION_MAX ? `${text.slice(0, QUESTION_MAX - 1)}…` : text
+}

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!)),
+    },
+  ]
+}