@huynle/hub 0.9.2 → 0.10.0

package/src/spoke/hub-tool.ts

@@ -6,6 +6,8 @@
 // phase 3): the only credential the hub lets a session act with, which the spoke never puts in any environment.
 // toolIdentity picks the token per verb and never falls back from one kind to the other. Messages from other sessions are shown in the
 // hub's envelope (packages/sdk/src/envelope.ts), sanitised, and marked as not coming from the user.
+// Each result's metadata carries a one-line title (src/spoke/hub-tool-title.ts) that reads like an incoming notice.
+import { withHubToolTitle } from "./hub-tool-title"
 import {
   HubClient,
   HubError,
@@ -27,7 +29,8 @@ import {
   type TeamIntakeStatusInput,
   wakeSkipNote,
 } from "../../packages/sdk/src/index.ts"
-import { ME_LINE, reachText, whoSections } from "./who-teams"
+import { ME_LINE, reachText, titleText, whoSections, YOU_MARK, youLine } from "./who-teams"
+import { HUB_TOOL_SUBSCRIPTION_VERBS, SUBSCRIPTION_TOOL_DESCRIPTION, SUBSCRIPTION_TOOL_INPUT, subscriptionVerb } from "./hub-tool-subscriptions"
 
 export const HUB_TOOL = "hub"
 
@@ -47,11 +50,13 @@ export const HUB_TOOL_SELF_VERBS = ["name", "role_claim", "role_release"] as con
  * concierge_find looks the user's sessions up by @name or title words through GET /api/agent/sessions?q=, an ordinary
  * read that any session (and the user) may make: it is a Concierge verb only for its framed, untrusted output. (FX-07)
  * Text without a letter or digit is answered here without a request (the hub would match nothing).
+ * (Concierge grant requests) concierge_request_grant asks the user for a scoped grant (POST …/grant-requests: a tap
+ * Decision; the hub clamps it).
  */
-export const HUB_TOOL_CONCIERGE_VERBS = ["concierge_board", "concierge_decisions", "concierge_decision", "concierge_notes", "concierge_notes_set", "concierge_watch", "concierge_unwatch", "concierge_mute", "concierge_unmute", "concierge_arm", "concierge_propose", "concierge_find", "concierge_form"] as const
+export const HUB_TOOL_CONCIERGE_VERBS = ["concierge_board", "concierge_decisions", "concierge_decision", "concierge_notes", "concierge_notes_set", "concierge_watch", "concierge_unwatch", "concierge_mute", "concierge_unmute", "concierge_arm", "concierge_propose", "concierge_find", "concierge_form", "concierge_request_grant"] as const
 export type HubToolConciergeVerb = (typeof HUB_TOOL_CONCIERGE_VERBS)[number]
 
-export const HUB_TOOL_VERBS = ["msg", "ask", "reply", "decline", "inbox", "who", "status", "show", "whoami", "intake", "intake_update", ...HUB_TOOL_SELF_VERBS, ...HUB_TOOL_ACT_VERBS, ...HUB_TOOL_CONCIERGE_VERBS] as const
+export const HUB_TOOL_VERBS = ["msg", "ask", "reply", "decline", "inbox", "who", "status", "show", "whoami", "intake", "intake_update", ...HUB_TOOL_SUBSCRIPTION_VERBS, ...HUB_TOOL_SELF_VERBS, ...HUB_TOOL_ACT_VERBS, ...HUB_TOOL_CONCIERGE_VERBS] as const
 export type HubToolVerb = (typeof HUB_TOOL_VERBS)[number]
 
 /** Which of the session's tokens a verb uses: "act" for act and Concierge verbs, "shell" for every other verb. */
@@ -75,8 +80,9 @@ export const HUB_TOOL_DESCRIPTION =
   "msg (tell a session something: to, text; urgent steers into its running turn; wake:false does not start a turn), " +
   "ask (ask a question: to, text; wait = seconds to block for the answer, at most 600; without wait the answer arrives later as a hub message), " +
   "reply (answer a message: id, text), decline (decline an ask: id, text = the reason), " +
-  "inbox (open asks to you, your open asks, recent messages), who (named and role-holding sessions; project, role, team; grouped by team with your reach to each), " +
+  "inbox (open asks to you, your open asks, recent messages), who (sessions: online ones, and named or role-holding ones while offline, yours first and marked; project, role, team; grouped by team with your reach to each), " +
   "status (machines, projects, sessions and what needs attention, with request IDs), show (one session: session; its state and blockers with the request and form IDs approve, deny and answer take), whoami (this session's hub identity). " +
+  SUBSCRIPTION_TOOL_DESCRIPTION +
   "This session itself (never another): name (set your @name: name, e.g. @billing-lead; your previous name stays an alias for 24 h; a taken name fails with name_taken), " +
   "role_claim (hold a role so @@role reaches you: role, project scopes it to a project, exclusive to be its only holder; reserved roles such as orchestrator are the user's to assign), role_release (role, project). " +
   "Team intake, for the session in a team's entry role: intake (team = the team's ID; id = an intake ID for one item, else the list), " +
@@ -94,11 +100,11 @@ export const HUB_TOOL_INPUT = {
   type: "object",
   properties: {
     verb: { type: "string", enum: [...HUB_TOOL_VERBS], description: "What to do." },
-    to: { type: "string", description: "msg/ask: the recipient address (@name, @@role, @@role#team, @name.project, ses_…, @me)." },
+    to: { type: "string", description: "msg/ask: the recipient address (@name, @@role, @@role#team, @name.project, ses_…, @me); subscribe: what to follow (a session, @@role, #team or children; several separated by commas)." },
     text: { type: "string", description: "msg/ask/reply: the message text; decline: the reason; prompt: the prompt." },
-    id: { type: "string", description: "reply/decline: the ID of the message you answer (from its [hub] header); approve/deny: the permission request's ID; answer: the form's ID; intake/intake_update: the intake ID (itk_…)." },
+    id: { type: "string", description: "reply/decline: the ID of the message you answer (from its [hub] header); approve/deny: the permission request's ID; answer: the form's ID; intake/intake_update: the intake ID (itk_…); unsubscribe: the subscription's ID (sub_…)." },
     wait: { type: "number", description: "ask: seconds to wait for the answer (0–600, default 0)." },
-    expires: { type: "number", description: "ask: seconds until the ask expires (the hub's default when unset)." },
+    expires: { type: "number", description: "ask: seconds until the ask expires (the hub's default when unset); subscribe: seconds until the subscription ends (default a day, at most 30 days)." },
     urgent: { type: "boolean", description: "msg/ask: steer into the recipient's running turn." },
     wake: { type: "boolean", description: "msg/ask/reply: false admits the message without starting a turn." },
     all: { type: "boolean", description: "msg/ask: send to every holder of a role address (no wait)." },
@@ -109,7 +115,7 @@ export const HUB_TOOL_INPUT = {
     why: { type: "string", description: "approve/deny/answer/prompt/stop: why (audited; deny passes it to the harness)." },
     answer: { type: "object", description: "answer: the form's answer, field key → value (text, number, true/false or a list of texts)." },
     cancel: { type: "boolean", description: "answer: dismiss the form instead of answering." },
-    delivery: { type: "string", enum: ["queue", "steer"], description: "prompt: how it enters a busy session." },
+    delivery: { type: "string", enum: ["queue", "steer", "silent"], description: "prompt: how it enters a busy session (queue or steer); subscribe: queue (default), steer or silent." },
     project: { type: "string", description: "who: only this project; role_claim/role_release: the project the role is scoped to." },
     role: { type: "string", description: "who: only holders of this role; role_claim/role_release: the role (reviewer or @@reviewer)." },
     team: { type: "string", description: "who: only this team (one of yours, when you are in teams); intake/intake_update: the team's ID (team_…)." },
@@ -117,7 +123,14 @@ export const HUB_TOOL_INPUT = {
     reason: { type: "string", description: "intake_update: why it failed or was cancelled (one line)." },
     revision: { type: "number", description: "intake_update: the revision you read (optional: the current one is read first)." },
     propose: { type: "string", enum: ["stop", "deny", "prompt", "answer"], description: "concierge_propose: the act to propose to the user." },
+    ...SUBSCRIPTION_TOOL_INPUT,
     recommend: { type: "boolean", description: "concierge_propose and approve: true only when YOU recommend doing it (shown as recommended, with why). Leave it out when the user only asked you to propose or try." },
+    projects: { type: "array", items: { type: "string" }, description: "concierge_request_grant: the watched projects (as your sessions name them) the grant covers." },
+    verbs: { type: "array", items: { type: "string" }, description: "concierge_request_grant: approve, deny, answer (prompt, stop only with userAsked)." },
+    permissions: { type: "array", items: { type: "string" }, description: "concierge_request_grant: the permissions approve may allow (read, edit, …)." },
+    never: { type: "array", items: { type: "string" }, description: "concierge_request_grant: extra never rules (the user's are added by the hub)." },
+    hours: { type: "number", description: "concierge_request_grant: how long the grant lasts after approval (default 8, at most 24)." },
+    userAsked: { type: "boolean", description: "concierge_request_grant: true only when the user explicitly asked for prompt or stop." },
   },
   required: ["verb"],
   additionalProperties: false,
@@ -193,7 +206,8 @@ export async function runHubTool(spoke: () => HubToolSpoke | undefined, value: u
   const secrets = [identity.token, toolIdentity(current, context.sessionID, kind === "act" ? "shell" : "act")?.token]
   const redact = (result: HubToolResult): HubToolResult => secrets.reduce((out, token) => (token ? scrub(out, token) : out), result)
   try {
-    return redact(await dispatch(client, verb as HubToolVerb, input, context))
+    // The title (metadata only) is redacted with the rest: the text it quotes is the agent's.
+    return redact(withHubToolTitle(input, await dispatch(client, verb as HubToolVerb, input, context)))
   } catch (cause) {
     if (cause instanceof InputError) return failure(cause.message, "invalid")
     const needsUser = needsUserOf(cause)
@@ -255,20 +269,22 @@ async function dispatch(client: HubClient, verb: HubToolVerb, input: Input, cont
       const answer = await client.who({ ...(project ? { project } : {}), ...(role ? { role } : {}), ...(team ? { team } : {}), ...signal })
       const { sessions } = answer
       const teams = (answer.teams ?? []).map((t) => ({ ...t, name: sanitizeLabel(t.name), yourRoles: (t.yourRoles ?? []).map((r) => sanitizeLabel(r)) }))
-      const rows = sessions.map((s) => ({ ...s, teams: (s.teams ?? []).map((t) => ({ ...t, team: sanitizeLabel(t.team) })) }))
-      const lines: string[] = []
-      for (const section of whoSections(rows, { teams, ...(answer.scope ? { scope: answer.scope } : {}) })) {
+      const rows = sessions.map((s) => ({ ...s, ...(s.name ? { name: sanitizeLabel(s.name) } : {}), ...(s.project ? { project: sanitizeLabel(s.project) } : {}), teams: (s.teams ?? []).map((t) => ({ ...t, team: sanitizeLabel(t.team) })) }))
+      const meta = { ...(teams.length ? { teams: teams.length } : {}), ...(answer.scope ? { scope: answer.scope } : {}) }
+      if (!rows.length) return { content: "No sessions to show.", metadata: { verb, sessions: 0, ...meta } }
+      const you = context.sessionID
+      const lines = [youLine(rows.find((s) => s.sessionID === you), you, "the name verb sets one")]
+      for (const section of whoSections(rows, { teams, you, ...(answer.scope ? { scope: answer.scope } : {}) })) {
         if (section.title) lines.push(section.title)
         for (const { row: s, teamRoles, reach } of section.rows) {
           const roles = (teamRoles ?? s.roles.map((r) => r.role)).map((r) => `@@${sanitizeLabel(r)}`).join(" ")
-          const tail = teamRoles && s.sessionID === context.sessionID ? "you" : reachText(reach)
-          const parts = [s.name ? `@${sanitizeLabel(s.name)}` : s.sessionID, s.name ? s.sessionID : "", s.project ? sanitizeLabel(s.project) : "", s.state ?? "", s.online ? "online" : "offline", s.harness ? sanitizeLabel(s.harness) : "", roles, tail]
+          const label = [s.name ? `@${s.name}` : s.sessionID, s.sessionID === you ? YOU_MARK : ""].filter(Boolean).join(" ")
+          const parts = [label, s.name ? s.sessionID : titleText(s.title ? sanitizeLabel(s.title) : undefined), s.project ?? "", s.state ?? "", s.online ? "online" : "offline", s.harness ? sanitizeLabel(s.harness) : "", roles, reachText(reach)]
           lines.push((section.title ? "  " : "") + parts.filter(Boolean).join(" · "))
         }
       }
-      if (answer.scope === "team" && lines.length) lines.push(ME_LINE)
-      const meta = { ...(teams.length ? { teams: teams.length } : {}), ...(answer.scope ? { scope: answer.scope } : {}) }
-      return { content: lines.length ? lines.join("\n") : "No named or role-holding sessions.", metadata: { verb, sessions: sessions.length, ...meta } }
+      if (answer.scope === "team") lines.push(ME_LINE)
+      return { content: lines.join("\n"), metadata: { verb, sessions: sessions.length, ...meta } }
     }
     case "show": {
       const addr = typeof input.session === "string" ? input.session.trim() : ""
@@ -312,6 +328,10 @@ async function dispatch(client: HubClient, verb: HubToolVerb, input: Input, cont
     case "intake":
     case "intake_update":
       return intake(client, verb, input, signal)
+    case "subscribe":
+    case "unsubscribe":
+    case "subscriptions":
+      return subscriptionVerb(client, verb, input, signal)
     case "name":
     case "role_claim":
     case "role_release":
@@ -329,6 +349,7 @@ async function dispatch(client: HubClient, verb: HubToolVerb, input: Input, cont
     case "concierge_propose":
     case "concierge_find":
     case "concierge_form":
+    case "concierge_request_grant":
       return conciergeVerb(client, verb, input, signal)
     case "whoami": {
       const { actor, user } = await client.whoami(signal)
@@ -499,7 +520,7 @@ function sent(verb: string, result: Sent): HubToolResult {
   const { message } = result
   return {
     content: `${verb === "decline" ? "Declined" : verb === "reply" ? "Replied" : "Sent"} ${message.id} to ${partyText(message)} (${deliveryNote(result)}).`,
-    metadata: { verb, id: message.id, ...deliveryMetadata(result) },
+    metadata: { verb, id: message.id, to: partyText(message), ...deliveryMetadata(result) },
   }
 }
 
@@ -764,6 +785,23 @@ async function conciergeVerb(client: HubClient, verb: HubToolConciergeVerb, inpu
         : "Nothing is armed."
       return { content, metadata: { verb, decisionID: r.armed?.decisionID ?? null } }
     }
+    case "concierge_request_grant": {
+      const list = (key: string, required: boolean) => {
+        const value = input[key]
+        if (value === undefined && !required) return {}
+        if (!Array.isArray(value) || (required && value.length === 0)) throw new InputError(`hub ${verb}: "${key}" is a list${required ? " (at least one)" : ""}`)
+        return { [key]: value }
+      }
+      const body: Record<string, unknown> = { ...list("projects", true), ...list("verbs", true), ...list("permissions", false), ...list("never", false) }
+      if (input.hours !== undefined) body.hours = input.hours
+      if (input.userAsked !== undefined) body.userAsked = input.userAsked
+      body.why = str(input, "why", verb)
+      const { decision } = await client.call<{ decision: { id: string; tier: string } }>("POST", `${CONCIERGE_PATH}/grant-requests`, { body, ...signal })
+      return {
+        content: `Requested the grant: Decision ${decision.id} (${decision.tier}) waits for the user's tap on the card in the Concierge panel. Do not retry and do not arm it; tell the user it waits for their tap.`,
+        metadata: { verb, decisionID: decision.id, tier: decision.tier },
+      }
+    }
     case "concierge_propose": {
       const propose = input.propose
       if (propose !== "stop" && propose !== "deny" && propose !== "prompt" && propose !== "answer") throw new InputError(`hub ${verb}: "propose" is stop, deny, prompt or answer`)

package/src/spoke/session-context.ts

@@ -16,7 +16,7 @@
 // LOCKED sessions (the Concierge's, R1 of the CON-04 verify): a context with lockAgent locks its session for good.
 // A locked session, WHATEVER agent it runs on and with or without a context (cleared, or not re-sent yet after a
 // restart), keeps only CONCIERGE_TOOLS (intersected with its context's allow-list), never gets conversation mode,
-// voice style or orchestrator parts. Locks survive `clear`, the context bound and a restart: they are persisted in
+// voice style or a voice front. Locks survive `clear`, the context bound and a restart: they are persisted in
 // the plugin's state dir (lockFile), so a restarted OpenCode locks the session before the hub reconnects. The agent
 // a locked session was last seen on is reported to the hub (SessionInfo.agent), which suspends a Concierge found on
 // another agent.
@@ -32,6 +32,8 @@ interface Context {
   readonly tail: readonly string[]
   readonly deny: readonly string[]
   readonly allow?: ReadonlySet<string>
+  /** (P2) The compact board for the session's voice front (never in the session's own prompt). */
+  readonly frontBoard?: string
 }
 
 /** Parts at the end of the system prompt (stable between turns), in this order. */
@@ -277,7 +279,8 @@ export class SessionContexts {
     const byKey = new Map(req.parts.map((p) => [p.key, p.text]))
     const pick = (keys: readonly SessionContextKey[]) => keys.flatMap((key) => (byKey.has(key) ? [byKey.get(key)!] : []))
     const allow = req.tools?.allow
-    this.contexts.set(req.sessionID, { revision: req.revision, parts: pick(SYSTEM_KEYS), tail: pick(TAIL_KEYS), deny: [...(req.tools?.deny ?? [])], ...(allow ? { allow: new Set(allow) } : {}) })
+    const frontBoard = byKey.get("frontBoard")
+    this.contexts.set(req.sessionID, { revision: req.revision, parts: pick(SYSTEM_KEYS), tail: pick(TAIL_KEYS), deny: [...(req.tools?.deny ?? [])], ...(allow ? { allow: new Set(allow) } : {}), ...(frontBoard !== undefined ? { frontBoard } : {}) })
     this.bound(this.contexts)
     return { revision: req.revision }
   }
@@ -301,6 +304,11 @@ export class SessionContexts {
     return [...(this.contexts.get(sessionID)?.tail ?? [])]
   }
 
+  /** (P2) The compact board the hub sent for the session's voice front (frontBoard part), if any. */
+  frontBoard(sessionID: string): string | undefined {
+    return this.contexts.get(sessionID)?.frontBoard
+  }
+
   /** A Concierge session: only CONCIERGE_TOOLS, its agent and model kept, no conversation mode. */
   locked(sessionID: string): boolean {
     if (!this.locks.has(sessionID)) this.refresh()