@huynle/hub 0.7.4 → 0.8.1

package/src/central/agent/decisions.ts

@@ -20,6 +20,11 @@
 // - close(): a Decision whose subject went away (a permission answered elsewhere) is closed, not answered; the asker
 //   hears why.
 // - 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.
+// - (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"
 import type { AgentActor, UserActor } from "./actor"
 import type { Delivery } from "./delivery"
@@ -37,6 +42,22 @@ export type DecisionState = "open" | "answered" | "expired" | "closed"
 export const URGENCIES: readonly Urgency[] = ["low", "normal", "high"]
 export const TIERS: readonly Tier[] = ["confirm", "tap"]
 export const DECISION_STATES: readonly DecisionState[] = ["open", "answered", "expired", "closed"]
+/** (CON-06) How the user answered: tap (the default, absent), or voice/text in the Concierge panel. */
+export type AnswerVia = "tap" | "voice" | "text"
+export const ANSWER_VIAS: readonly AnswerVia[] = ["tap", "voice", "text"]
+/** The refusal of a voice/text answer the hub does not admit. */
+export const TAP_ONLY = "Answer this decision with a tap"
+/** The refusal of a voice/text answer that picks a lasting option (coordinator decision, 93265or7). */
+export const ALWAYS_TAP_ONLY = "Answer 'always' with a tap"
+
+/**
+ * Whether an option is not once-off: `always` (saves a lasting rule, e.g. an escalated permission approved for
+ * good), or approving a grant request (creates a lasting grant). Voice and text pick only once-off options.
+ */
+export function lastingOption(decision: Pick<Decision, "action" | "options">, option: string | undefined): boolean {
+  if (option === "always") return true
+  return decision.action?.kind === "grant" && !decision.options.some((o) => o.id === option && o.safe)
+}
 
 /** Options a Decision offers. */
 export const OPTIONS_MAX = 8
@@ -67,10 +88,27 @@ export interface DecisionAnswer {
   readonly at: number
   /** The device the user answered from. */
   readonly deviceID?: string
+  /** (CON-06) voice or text; absent = tap. */
+  readonly via?: "voice" | "text"
 }
 
 /** What answering a Decision does besides replying: an escalated permission request (P3-T8) or a grant request (P3-T9). */
-export type DecisionAction = PermissionAction | GrantRequestAction
+export type DecisionAction = PermissionAction | GrantRequestAction | ActAction
+
+/**
+ * (CON-06) A Concierge proposal (concierge/proposals.ts): answering `go` runs the act verb on the target AS THE USER
+ * through the acting engine (tenancy re-checked); `hold` does nothing.
+ */
+export interface ActAction {
+  readonly kind: "act"
+  readonly verb: "stop" | "deny" | "prompt" | "answer"
+  /** The session ID it was proposed for (resolved when proposed). */
+  readonly target: string
+  /** The verb's validated input (requestID, formID, answer, text). */
+  readonly input: Readonly<Record<string, unknown>>
+  /** (FX-05) deny: the permission it would deny, for the console's card. */
+  readonly request?: DecisionRequest
+}
 
 /** An escalated permission request: the answer replies to it as the user. */
 export interface PermissionAction {
@@ -82,6 +120,56 @@ export interface PermissionAction {
   readonly sessionID: string
   /** The agent asked to approve it always. */
   readonly always: boolean
+  /** (FX-05) What it asks, for the console's card (absent when the hub did not know the request's details). */
+  readonly request?: DecisionRequest
+  /** (FX-05) Why the hub sent it to the user (the evaluation's reason). */
+  readonly reason?: string
+}
+
+/**
+ * (FX-05) A permission request as a Decision shows it (bounded): its kind, what it applies to and the patterns an
+ * "always" would save. What was not stored is recorded, so a shortened command never reads as complete: the totals
+ * when items were dropped, each cut item with its full length, and `truncated` when the hub received the request
+ * already shortened (src/status.ts permissionRequest). The console renders it as text; the Concierge's Decision reads
+ * leave it out (concierge/board-routes.ts conciergeDecisionView).
+ */
+export interface DecisionRequest {
+  readonly action: string
+  readonly resources: readonly string[]
+  readonly save?: readonly string[]
+  /** How many resources the request had, when more than were stored. */
+  readonly resourcesTotal?: number
+  /** How many save patterns it had, when more than were stored. */
+  readonly savesTotal?: number
+  /** Stored items cut at DECISION_REQUEST_TEXT characters, with their full length. */
+  readonly cut?: readonly { readonly field: "resources" | "save"; readonly index: number; readonly length: number }[]
+  /** The hub received the request already shortened. */
+  readonly truncated?: true
+}
+
+/** Resources (and save patterns) a Decision keeps of a request, and the characters of each. */
+export const DECISION_REQUEST_ITEMS = 20
+export const DECISION_REQUEST_TEXT = 2_000
+
+/** A permission request, bounded for a Decision, with what was not stored. */
+export function decisionRequest(request: { readonly action: string; readonly resources: readonly string[]; readonly save?: readonly string[]; readonly truncated?: true }): DecisionRequest {
+  const cut: { field: "resources" | "save"; index: number; length: number }[] = []
+  const bound = (field: "resources" | "save", list: readonly string[]) =>
+    list.slice(0, DECISION_REQUEST_ITEMS).map((r, index) => {
+      if (r.length > DECISION_REQUEST_TEXT) cut.push({ field, index, length: r.length })
+      return r.slice(0, DECISION_REQUEST_TEXT)
+    })
+  const resources = bound("resources", request.resources)
+  const save = request.save?.length ? bound("save", request.save) : undefined
+  return {
+    action: request.action.slice(0, DECISION_REQUEST_TEXT),
+    resources,
+    ...(save ? { save } : {}),
+    ...(request.resources.length > resources.length ? { resourcesTotal: request.resources.length } : {}),
+    ...(save && request.save!.length > save.length ? { savesTotal: request.save!.length } : {}),
+    ...(cut.length ? { cut } : {}),
+    ...(request.truncated ? { truncated: true as const } : {}),
+  }
 }
 
 /** A grant an agent requested (grant-requests.ts): approving creates it as the user. */
@@ -121,6 +209,8 @@ export interface Decision {
   readonly closed?: { readonly at: number; readonly reason: string }
   /** Run (as the answering user) when the user answers; set by the hub only, never by an asker. */
   readonly action?: DecisionAction
+  /** (CON-06) Asked by one of the user's Concierge sessions: the console says "by @@concierge". */
+  readonly as?: "concierge"
 }
 
 /** What the hub (never an asker's request) adds to an ask. */
@@ -148,8 +238,13 @@ export interface AskInput {
 export interface AnswerInput {
   readonly option?: string
   readonly text?: string
+  /** (CON-06) Absent = tap. */
+  readonly via?: AnswerVia
 }
 
+/** (CON-06) Admits a voice/text answer (throws forbidden otherwise). */
+export type ViaCheck = (userID: string, decision: Decision, via: "voice" | "text", by: UserActor) => Promise<void>
+
 export type NotifyReason = "opened" | "escalated"
 
 /**
@@ -177,6 +272,10 @@ export interface DecisionsDeps {
   readonly changed?: (userID: string, decision: Decision) => void
   /** Runs Decisions' actions (escalations); a Decision with an action cannot be answered without it. */
   readonly act?: DecisionActor
+  /** (CON-06) Admits voice/text answers; without it every voice/text answer is refused. */
+  readonly via?: ViaCheck
+  /** (CON-06) Whether a session is one of the user's Concierge sessions (current or past): the Decision's `as`. */
+  readonly concierge?: (userID: string, sessionID: string) => Promise<boolean>
 }
 
 const DECISIONS = "decisions"
@@ -274,6 +373,7 @@ export class Decisions {
     const v = validate(input)
     const about = [...new Set(input.about ?? (actor.kind === "session" ? [actor.sessionID] : []))]
     const { message } = await this.deps.delivery.send(userID, actor, "@me", "ask", input.question, { expiresInMs: v.expiresInMs })
+    const asConcierge = actor.kind === "session" && (await this.isConcierge(userID, actor.sessionID))
     const decision: Decision = {
       id: this.newID(),
       messageID: message.id,
@@ -291,6 +391,7 @@ export class Decisions {
       at: message.at,
       expiresAt: message.expiresAt ?? message.at + v.expiresInMs,
       ...(extra.action ? { action: extra.action } : {}),
+      ...(asConcierge ? { as: "concierge" as const } : {}),
     }
     const written = await this.deps.state.put(userID, DECISIONS, decision.id, decision, { ifVersion: 0 })
     if (!written.ok) throw new Error("decision id collision")
@@ -331,9 +432,18 @@ export class Decisions {
     if (!current || by.userID !== userID) throw notFound()
     if (current.state !== "open") throw gone()
     if (current.tier === "tap" && by.via !== "cookie") throw new AgentError("forbidden", "This decision needs a tap in the signed-in console", { hint: "Answer it in the console" })
+    const via = input.via ?? "tap"
+    if (!ANSWER_VIAS.includes(via)) throw invalid(`via is one of ${ANSWER_VIAS.join(", ")}`)
     const choice = this.choice(current, input)
+    if (via !== "tap") {
+      // Voice/text: confirm tier only, and only what the hub's check admits (never without one).
+      if (current.tier !== "confirm" || !this.deps.via) throw new AgentError("forbidden", TAP_ONLY, { hint: "Tap an option" })
+      // Only once-off options by voice or text: a lasting one (always, a grant) needs a tap.
+      if (lastingOption(current, choice.option)) throw new AgentError("forbidden", ALWAYS_TAP_ONLY, { hint: "Tap the option" })
+      await this.deps.via(userID, current, via, by)
+    }
     const at = this.now()
-    const answer: DecisionAnswer = { ...choice, answeredBy: "user", at, deviceID: by.deviceID }
+    const answer: DecisionAnswer = { ...choice, answeredBy: "user", at, deviceID: by.deviceID, ...(via !== "tap" ? { via } : {}) }
     const decision = await this.settle(userID, id, answer)
     if (!decision) throw gone()
     const note = decision.action ? await this.runAction(userID, decision, choice, by) : undefined
@@ -399,6 +509,19 @@ export class Decisions {
 
   // ---- internals ----------------------------------------------------------------------------------------
 
+  /**
+   * Whether the session is one of the user's Concierge sessions; a failed read is no label (never fails the ask).
+   * (FX-07) A read that timed out (`busy`) refuses the ask instead: the label could not be checked (fail closed).
+   */
+  private async isConcierge(userID: string, sessionID: string): Promise<boolean> {
+    try {
+      return (await this.deps.concierge?.(userID, sessionID)) === true
+    } catch (cause) {
+      if (cause instanceof AgentError && cause.code === "busy") throw cause
+      return false
+    }
+  }
+
   /** Tells the changed listener (its failure never fails the caller). */
   private emit(userID: string, decision: Decision): void {
     try {