@huynle/hub 0.9.2 → 0.10.0

package/src/central/agent/decisions.ts

@@ -5,9 +5,13 @@
 //   deadline?, onTimeout?, state, at, expiresAt, escalatedAt?, answer?}, per user in the StateStore. The ask
 //   message (stored by the delivery engine, recipient the user) carries it: it closes when the Decision is
 //   answered, and the Decision expires with it.
-// - Only the user answers (never a session or app, never the asker); `tap` Decisions only from a signed-in
-//   console (the device cookie, not a device token). The first answer wins (a version-checked write); later
-//   ones get `gone`. The answer goes back to the asker as the user's reply to the ask.
+// - The user answers (never a session, never the asker); `tap` Decisions only from a signed-in console (the device
+//   cookie, not a device token). (AF4, contract §6, superseding CON-06's "only the user's device answers" for this
+//   case only) an app holding `decisions:answer` may answer a CONFIRM-tier Decision without an action, not
+//   Concierge-asked, that one of its own sessions asked (answerByApp; app-decisions.ts), with a once-off option
+//   only; recorded answeredBy "app" with its party. The first answer wins across the console and apps (a
+//   version-checked write); later ones get `gone`. The answer goes back to the asker as the user's reply to the ask
+//   (an app's says which app answered).
 // - Deadlines: at the deadline, `onTimeout` (only an option marked safe) answers it, recorded answeredBy
 //   "timeout"; without one the Decision stays open and escalates once (notified again). The loop (start/tick)
 //   looks at every user's open Decisions, so deadlines survive restarts.
@@ -22,7 +26,8 @@
 // - Every open and change (answer, timeout, escalation, expiry, close) goes to `changed` (the console's 'decision' event).
 // - (CON-06) `via`: an answer is a tap unless it says voice or text. Voice/text answers only a confirm-tier
 //   Decision, and only when the hub's `via` check admits it (the Concierge tiers: armed, presence, the user's
-//   device); otherwise forbidden "Answer this decision with a tap". Never a model: only the user's device answers.
+//   device); otherwise forbidden "Answer this decision with a tap". Never a model: the user's device answers (or,
+//   AF4, an app for its own sessions' confirm-tier Decisions; never by voice or text: an app's answer has no `via`).
 // - (CON-06) `as: "concierge"`: set when the asker is one of the user's Concierge sessions (current or past), so
 //   the console can say "by @@concierge". The `act` action kind is a Concierge proposal (concierge/proposals.ts).
 import type { Clock, StateStore, Timers } from "../backend/types"
@@ -34,7 +39,7 @@ import { ASK_EXPIRES_MAX_MS, ASK_EXPIRES_MIN_MS, ASK_EXPIRES_MS, type Message, n
 import { updateVersioned } from "./versioned"
 
 export type Urgency = "low" | "normal" | "high"
-/** confirm: any of the user's signed-in devices; tap: only a signed-in console (cookie). */
+/** confirm: any of the user's signed-in devices (AF4: or an app, for its own sessions' asks); tap: only a signed-in console (cookie). */
 export type Tier = "confirm" | "tap"
 /** closed: ended without an answer because what it asked about went away (answered elsewhere, ended). */
 export type DecisionState = "open" | "answered" | "expired" | "closed"
@@ -84,12 +89,38 @@ export interface DecisionOption {
 export interface DecisionAnswer {
   readonly option?: string
   readonly text?: string
-  readonly answeredBy: "user" | "timeout"
+  /** (AF4) "app": an app holding decisions:answer answered a confirm-tier Decision of its own session. */
+  readonly answeredBy: "user" | "timeout" | "app"
   readonly at: number
   /** The device the user answered from. */
   readonly deviceID?: string
   /** (CON-06) voice or text; absent = tap. */
   readonly via?: "voice" | "text"
+  /** (AF4) The app that answered (its party, `app:<tokenID>`; answeredBy "app"). */
+  readonly app?: string
+  /** (AF4) The app's label when it answered (sanitised), for the console's "answered by". */
+  readonly appLabel?: string
+}
+
+/** (AF4) The app answering a Decision: its party (`app:<tokenID>`) and label. */
+export interface AppAnswerer {
+  readonly party: string
+  readonly label?: string
+}
+
+/** (AF4) The refusal of a Decision only the user answers (tap tier, an action, a Concierge ask). */
+export const NEEDS_THE_USER = "This decision needs the user"
+
+/**
+ * (AF4, contract §6) Why an app may not answer this Decision whatever its option, or undefined: only a confirm-tier
+ * Decision without an action (no escalated permission, grant request or Concierge proposal) that no Concierge
+ * session asked. Ownership (the asker is the app's session) and the state are the caller's checks.
+ */
+export function appAnswerRefusal(decision: Pick<Decision, "tier" | "action" | "as">): AgentError | undefined {
+  if (decision.tier !== "confirm" || decision.action !== undefined || decision.as === "concierge") {
+    return new AgentError("forbidden", NEEDS_THE_USER, { hint: "The user answers it in the console" })
+  }
+  return undefined
 }
 
 /** What answering a Decision does besides replying: an escalated permission request (P3-T8) or a grant request (P3-T9). */
@@ -179,6 +210,8 @@ export interface GrantRequestAction {
   readonly requester: string
   /** The grant body (validated when requested; validated again, as the user's, on approval). */
   readonly grant: Readonly<Record<string, unknown>>
+  /** The Concierge's own request (concierge/grant-request.ts): created with the managed @@concierge holder. */
+  readonly managed?: true
 }
 
 export interface Decision {
@@ -454,6 +487,38 @@ export class Decisions {
     return { decision, ...(await this.replyTo(userID, decision, text, by)) }
   }
 
+  /**
+   * (AF4, contract §6) An app answers a Decision of its own session: `owned` (the asker is the app's session; false →
+   * not_found, like an unknown ID) first, then open (else gone), appAnswerRefusal (forbidden), the choice (invalid), a
+   * once-off option (a lasting one is forbidden), `ready` (the kill switch: paused), and the version-checked settle:
+   * the first answer wins across console and apps (a lost race is gone). The asker hears which app answered.
+   */
+  async answerByApp(
+    userID: string,
+    id: string,
+    input: { readonly option?: string; readonly text?: string },
+    app: AppAnswerer,
+    checks: { readonly owned: (decision: Decision) => Promise<boolean>; readonly ready?: (decision: Decision) => void },
+  ): Promise<{ decision: Decision; reply?: Message }> {
+    const current = await this.get(userID, id)
+    if (!current || !(await checks.owned(current))) throw notFound()
+    if (current.state !== "open") throw gone()
+    const refused = appAnswerRefusal(current)
+    if (refused) throw refused
+    const choice = this.choice(current, input)
+    if (lastingOption(current, choice.option)) throw new AgentError("forbidden", NEEDS_THE_USER, { hint: "A lasting option needs the user's tap" })
+    checks.ready?.(current)
+    const label = app.label === undefined ? undefined : sanitizeLabel(app.label, OPTION_LABEL_MAX) || undefined
+    const answer: DecisionAnswer = { ...choice, answeredBy: "app", app: app.party, ...(label ? { appLabel: label } : {}), at: this.now() }
+    const decision = await this.settle(userID, id, answer)
+    if (!decision) throw gone()
+    this.emit(userID, decision)
+    const option = decision.options.find((o) => o.id === choice.option)
+    const by = `(answered by the app “${label ?? app.party}”)`
+    const text = option ? `Decision ${id}: ${option.label} [${option.id}] ${by}${choice.text ? `\n${choice.text}` : ""}` : `Decision ${id}: ${choice.text} ${by}`
+    return { decision, ...(await this.replyTo(userID, decision, text, HUB_USER(userID))) }
+  }
+
   /**
    * Closes an open Decision without an answer (what it asked about went away: answered elsewhere, ended) and tells
    * the asker why. Undefined (no change) when it is not open, unknown or another user's.

package/src/central/agent/delivery.ts

@@ -55,6 +55,7 @@ import type { TeamPolicy } from "../teams/policy"
 import type { AgentActor } from "./actor"
 import type { DirectoryEntry, NamedListener, Resolved } from "./directory"
 import { type Party, type PartyInfo, partyFromActor, partyKey, partyLabel, renderEnvelope, renderPrimer } from "./envelope"
+import { noticeOnly } from "../../../packages/sdk/src/envelope.ts"
 import { AgentError } from "./errors"
 import { type ExpiredReason, parseNotAfter } from "./not-after"
 import { HOP_CAP, HopTracker, MessageLimiter, type MessageLimits, overHopCap } from "./message-limits"
@@ -593,6 +594,8 @@ export class Delivery {
     const from = this.party(userID, actor)
     const original = await this.messages.get(userID, replyTo)
     const to = original && partyKey(original.recipient) === partyKey(from) ? original.from : undefined
+    // Subscription notices are read by no one: a reply would go nowhere (refused before anything is stored).
+    if (to && noticeOnly(to)) throw new AgentError("invalid", "Subscription notices take no reply: react in your own turn, or stop them with hub unsubscribe <sub_…>")
     if (original) await this.deps.inbound?.outbound?.(userID, from, kind, original)
     if (to?.kind === "session") {
       await this.deps.inbound?.admit(userID, from, to.sessionID, kind, original)

package/src/central/agent/directory.ts

@@ -157,6 +157,11 @@ export class Directory {
     })
   }
 
+  /** (AF3) Whether the session was deleted (and no process reports it again). */
+  deleted(userID: string, sessionID: string): boolean {
+    return this.read(userID, (draft) => draft.byID.get(sessionID)?.deletedAt !== undefined)
+  }
+
   // ---------- primer ----------
 
   /** Whether the identity primer reached the session (false for an unknown one). */

package/src/central/agent/errors.ts

@@ -35,6 +35,8 @@ export const AGENT_ERROR_STATUS = {
   rate_limited: 429,
   /** An unexpected failure (details are logged, not sent). */
   internal: 500,
+  /** (AF2) The user's speech provider failed (`retryAfter` when it gave one). */
+  upstream_failed: 502,
   /** The machine is offline (actions only; messages queue instead). */
   offline: 503,
   /** (FX-07) The hub's state did not answer in time (`retryAfter`, seconds): refused, try again. */

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

@@ -18,6 +18,11 @@
 //   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).
+// - (Concierge grant requests) requestManaged: the Concierge's own request (concierge/grant-request.ts builds and
+//   clamps the grant; holder @@concierge, which only a managed create may name). Keyed by the caller's key (one for
+//   all the user's Concierge sessions), with an optional denial cooldown: after the user denied the last one, no new
+//   request until it passes (rate_limited). Its action carries managed: true (the hub's, never the asker's), so the
+//   approval creates the grant with the managed holder.
 import type { Counters, StateStore } from "../backend/types"
 import type { AgentActor, AppActor, SessionActor, UserActor } from "./actor"
 import type { AgentAudit } from "./audit"
@@ -25,7 +30,7 @@ import { type ActOutcome, type Decision, type Decisions, WHY_MAX } from "./decis
 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 { Grant, Grants } from "./grants"
 import type { Message } from "./messages"
 import { parseAddress } from "./names"
 import { type GrantSpec, validateGrant } from "./policy"
@@ -57,9 +62,19 @@ export interface GrantRequestsDeps {
   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
+  /** A grant was created on the user's approval (the Concierge's context refresh). Never throws through. */
+  readonly granted?: (userID: string, grant: Grant) => void
   readonly now?: () => number
 }
 
+/** How requestManaged keys and limits a request. */
+export interface ManagedRequestOptions {
+  /** The record key (one open request per key). */
+  readonly key: string
+  /** After the user denied the key's last request, no new one for this long (rate_limited). */
+  readonly cooldownMs?: 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)
@@ -84,16 +99,33 @@ export class GrantRequests {
     const spec = validateGrant({ ...body.grant, holder: body.grant.holder ?? own })
     const holder = this.holder(userID, actor, spec.holder, own)
     await this.deps.grants.assertHolder?.(userID, holder)
-    const grant = canonical({ ...spec, holder })
-
     const requester = this.describe(userID, actor)
-    const key = partyKey(requester)
+    return this.open(userID, actor, requester, spec, holder, why, { key: partyKey(requester) })
+  }
+
+  /**
+   * (Concierge) Opens the Decision for a grant the hub built for the session (holder as given, created managed on
+   * approval). The caller validated the session and the why. Throws invalid or rate_limited.
+   */
+  async requestManaged(userID: string, actor: SessionActor, input: { readonly grant: Record<string, unknown>; readonly why: string }, options: ManagedRequestOptions): Promise<{ decision: Decision; message: Message }> {
+    const spec = validateGrant(input.grant)
+    return this.open(userID, actor, this.describe(userID, actor), spec, spec.holder, input.why, options, true)
+  }
+
+  private async open(userID: string, actor: SessionActor | AppActor, requester: Party, spec: GrantSpec, holder: string, why: string, options: ManagedRequestOptions, managed = false): Promise<{ decision: Decision; message: Message }> {
+    const grant = canonical({ ...spec, holder })
+    const { key } = options
     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 } })
+      const last = await decisions.get(userID, existing.value.decisionID)
+      if (last?.state === "open") {
+        throw new AgentError("rate_limited", `Your grant request ${last.id} still waits for the user`, { extra: { retryAfter: 60, decisionID: last.id } })
+      }
+      const answer = last?.state === "answered" ? last.answer : undefined
+      if (options.cooldownMs !== undefined && answer?.answeredBy === "user" && answer.option !== "approve") {
+        const left = answer.at + options.cooldownMs - this.now()
+        if (left > 0) throw new AgentError("rate_limited", "The user denied your last grant request: do not ask again yet", { extra: { retryAfter: Math.ceil(left / 1000), decisionID: last!.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 } })
@@ -119,7 +151,7 @@ export class GrantRequests {
           urgency: "high",
           tier: "tap",
         },
-        { action: { kind: "grant", requester: key, grant } },
+        { action: { kind: "grant", requester: key, grant, ...(managed ? { managed: true as const } : {}) } },
       )
     } catch (cause) {
       await state.delete(userID, COLLECTION, key, { ifVersion: reserved.version })
@@ -143,13 +175,18 @@ export class GrantRequests {
     }
     let created
     try {
-      created = await this.deps.grants.create(userID, action.grant)
+      created = await this.deps.grants.create(userID, action.grant, action.managed ? { managed: true } : {})
     } 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" })
+    try {
+      this.deps.granted?.(userID, created)
+    } catch {
+      // A listener's failure never fails the approval.
+    }
     return { outcome: "done", note: `Grant ${created.id} created (holder ${created.holder}, until ${new Date(created.expiresAt).toISOString()})` }
   }
 

package/src/central/agent/grants.ts

@@ -66,6 +66,10 @@ export interface GrantsDeps {
   readonly now?: () => number
   /** (CON-04) The user's Concierge sessions: only the Concierge service (managed) grants to them or to @@concierge. */
   readonly concierge?: (owner: string) => Promise<readonly string[]>
+  /** (AF1) Whether the owner has a connected app of this ID (`app:<connection>` holders), besides hand-made tokens. */
+  readonly connections?: (owner: string, id: string) => boolean
+  /** (AF3) A grant of the owner was created, changed or revoked (open app streams re-check their ownership now). */
+  readonly changed?: (owner: string) => void
 }
 
 const notFound = () => new AgentError("not_found", "No such grant")
@@ -114,6 +118,7 @@ export class Grants {
     await this.deps.state.put(owner, COLLECTION, grant.id, grant)
     await this.prune(owner, all, at)
     await this.deps.admin?.audit({ actor: owner, action: "grant.create", target: grant.id })
+    this.deps.changed?.(owner)
     return grant
   }
 
@@ -165,6 +170,7 @@ export class Grants {
     })
     if (missing || !next) throw notFound()
     await this.deps.admin?.audit({ actor: owner, action, target: id })
+    this.deps.changed?.(owner)
     return next
   }
 
@@ -203,7 +209,7 @@ export class Grants {
   private holds(grant: Grant, actor: SessionActor | AppActor): boolean {
     if (grant.holder.startsWith("app:")) {
       if (actor.kind !== "app" || grant.holder !== `app:${actor.tokenID}`) return false
-      return (this.deps.store.agentData(grant.owner).appTokens ?? []).some((t) => t.id === actor.tokenID)
+      return this.appExists(grant.owner, actor.tokenID)
     }
     if (actor.kind !== "session") return false
     if (grant.holderSessionID !== undefined) return grant.holderSessionID === actor.sessionID
@@ -215,6 +221,11 @@ export class Grants {
     }
   }
 
+  /** An app credential of the owner: a hand-made token or (AF1) a connected app. */
+  private appExists(owner: string, id: string): boolean {
+    return (this.deps.store.agentData(owner).appTokens ?? []).some((t) => t.id === id) || this.deps.connections?.(owner, id) === true
+  }
+
   private owner(owner: string): void {
     const user = this.deps.store.user(owner)
     if (!user || user.disabled) throw new AgentError("not_found", "No such user")
@@ -224,7 +235,7 @@ export class Grants {
   private pin(owner: string, holder: string): string | undefined {
     if (holder.startsWith("app:")) {
       const id = holder.slice(4)
-      if (!(this.deps.store.agentData(owner).appTokens ?? []).some((t) => t.id === id)) throw new AgentError("not_found", `No app token ${id}`)
+      if (!this.appExists(owner, id)) throw new AgentError("not_found", `No app token or connected app ${id}`)
       return undefined
     }
     if (holder.startsWith("@@")) return undefined

package/src/central/agent/message-limits.ts

@@ -19,7 +19,7 @@
 //   at any pace (the S1 case; an app answering one session with new messages forever is held by the pair limit and
 //   the recipient's wake budget instead). A relay loop through an app thus reaches HOP_CAP after ~8 hops. Only
 //   session senders count (the user's hop 0 and other apps do not), and the hub's own parties (HUB_APP_TOKENS:
-//   app:concierge, the workspace coordinator, team intake) keep none: they send on events and submissions, not on
+//   app:concierge, the workspace coordinator, team intake, session subscriptions) keep none: they send on events and submissions, not on
 //   the messages they receive (team intake carries the submitter's depth + 1 itself, SendOptions.chainHop). It is
 //   not a persistent depth: messages to an app still raise nothing beyond this time-boxed memory.
 // - MessageLimiter: fixed windows aligned to the clock (so retryAfter is exact): messages per sender→recipient
@@ -41,7 +41,7 @@ export const RELAY_WINDOW_MS = 5 * 60_000
 /** Sending sessions remembered per (user, app); the oldest go first. */
 export const RELAY_SOURCES_MAX = 32
 /** The hub's own app parties (app:<tokenID>): no relay depth (see the header). */
-export const HUB_APP_TOKENS: ReadonlySet<string> = new Set(["concierge", "workspace-coordinator", "team-intake"])
+export const HUB_APP_TOKENS: ReadonlySet<string> = new Set(["concierge", "workspace-coordinator", "team-intake", "subscriptions"])
 
 /** StateStore collection: partyKey → HopDepth. */
 const HOPS = "message-hops"

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

@@ -10,12 +10,13 @@
 //   POST /api/agent/mute     {session}  /  POST /api/agent/unmute {session} messages:send → {muted}
 //   GET  /api/agent/messaging  /  PUT /api/agent/messaging {enabled}       user actors only: the per-user switch
 //   GET  /api/agent/decisions?state=  /  GET /api/agent/decisions/:id      messages:read → {decisions} / {decision}
+//   (AF4) GET /api/agent/decisions?answerable=1 is the app's answerable list (decisions:answer; app-decisions.ts)
 //
 // - @me (design §12.1): msg @me is stored for the user; ask @me opens a Decision (./decisions) with the extra
 //   fields {options: [{id, label, safe?}], recommendation: {option, why?}, urgency, tier, deadline (seconds),
 //   onTimeout, about: [addresses]} → 201 {message, decision, answer?}. Those fields on an ask to anyone else are
-//   invalid. Only the user answers a Decision, on the console (/api/decisions/:id/answer): its ask cannot be
-//   replied to or declined here. Decisions read for their asker (and the user); others get not_found.
+//   invalid. The user answers a Decision on the console (/api/decisions/:id/answer), or (AF4) an app its own
+//   sessions' confirm-tier ones (app-decisions.ts): its ask cannot be replied to or declined here. Decisions read for their asker (and the user); others get not_found.
 //
 // - The sender is only ever the authenticated actor; any from/sender in a body is ignored. A session cannot
 //   message itself (invalid). Replies and declines come only from the message's recipient; anyone else, and any
@@ -73,6 +74,8 @@ export interface MessageDeps {
   readonly feed: MessageFeed
   /** Decisions (ask @me); without them an ask to @me is a plain stored ask. */
   readonly decisions?: Decisions
+  /** (AF4) GET /api/agent/decisions?answerable=1 (app-decisions.ts); without it `answerable` is ignored. */
+  readonly answerable?: (context: AgentContext) => Promise<Response>
   /** Default WAIT_POLL_MS. */
   readonly pollMs?: number
   /** Where msg/ask keep their Idempotency-Key records; without it a key is checked for shape but not remembered. */
@@ -373,8 +376,14 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
           {
             method: "GET",
             path: `${AGENT_PREFIX}/decisions`,
-            allow: READ,
-            handle: async ({ user, actor, url }) => ok({ decisions: await decisionsFor(user.id, actor, decisionStateQuery(url.searchParams.get("state"))) }),
+            // (AF4) decisions:answer reaches it for ?answerable=1 only.
+            allow: deps.answerable ? { ...READ, scopes: ["messages:read", "decisions:answer"] } : READ,
+            async handle(context) {
+              const { user, actor, url } = context
+              if (deps.answerable && url.searchParams.has("answerable")) return deps.answerable(context)
+              if (actor.kind === "app" && !actor.scopes.includes("messages:read")) throw new AgentError("forbidden", "This credential cannot use this route")
+              return ok({ decisions: await decisionsFor(user.id, actor, decisionStateQuery(url.searchParams.get("state"))) })
+            },
           } satisfies AgentRoute,
           {
             method: "GET",

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

@@ -69,6 +69,11 @@ export interface ReadDeps {
   readonly discovery?: TeamDiscovery
   /** (CON-04) The user's Concierge sessions (current and hidden): their entries carry `concierge: true`. */
   readonly concierge?: (userID: string) => Promise<readonly string[]>
+  /**
+   * (AF3) Throws not_found unless the addressed session is the app's (contract §1.2): the log admits conversation:read
+   * (without sessions:read) for those only.
+   */
+  readonly appSession?: (actor: AgentActor, userID: string, addr: string) => Promise<unknown>
 }
 
 /** One session in agent answers (status, sessions). */
@@ -380,6 +385,8 @@ function sessionFilter(deps: ReadDeps, userID: string, params: URLSearchParams):
 const NO_STORE = { "cache-control": "no-store" }
 const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
 const READ = { session: true, scope: "sessions:read" } as const
+/** (AF3) The log: sessions:read, or conversation:read for the app's own sessions. */
+const LOG = { session: true, scopes: ["sessions:read", "conversation:read"] } as const
 
 export function readRoutes(deps: ReadDeps): AgentRoute[] {
   return [
@@ -418,8 +425,15 @@ export function readRoutes(deps: ReadDeps): AgentRoute[] {
     {
       method: "GET",
       path: `${AGENT_PREFIX}/sessions/:addr/log`,
-      allow: READ,
-      handle: async ({ user, params, url, actor }) => ok(await log(deps, user.id, params.addr!, url.searchParams.get("n"), await censusOf(deps, user.id, actor))),
+      allow: LOG,
+      handle: async ({ user, params, url, actor }) => {
+        // (AF3) conversation:read alone: the app's own sessions only.
+        if (actor.kind === "app" && !actor.scopes.includes("sessions:read")) {
+          if (!deps.appSession) throw new AgentError("forbidden", "This credential cannot use this route")
+          await deps.appSession(actor, user.id, params.addr!)
+        }
+        return ok(await log(deps, user.id, params.addr!, url.searchParams.get("n"), await censusOf(deps, user.id, actor)))
+      },
     },
     ...(deps.events ? [watchRoute(deps, deps.events)] : []),
   ]