@huynle/hub 0.10.0 → 0.11.0

package/src/central/recording/settings.ts

@@ -7,7 +7,15 @@ export const SETTINGS_COLLECTION = "voice-recording-settings"
 const KEY = "settings"
 export const DEFAULT_SETTINGS: RecordingSettings = { enabled: false, revision: 0 }
 
-export type SettingsWrite = { readonly ok: true; readonly settings: RecordingSettings; readonly changed: boolean } | { readonly ok: false; readonly currentRevision: number }
+export type SettingsWrite =
+  | { readonly ok: true; readonly settings: RecordingSettings; readonly changed: boolean; readonly developerChanged: boolean }
+  | { readonly ok: false; readonly currentRevision: number }
+
+/** A PUT's change: either or both (never enabled: false with developer: true, the route refuses it). */
+export interface SettingsChange {
+  readonly enabled?: boolean
+  readonly developer?: boolean
+}
 
 export class RecordingSettingsStore {
   constructor(
@@ -19,15 +27,21 @@ export class RecordingSettingsStore {
     return (await this.state.get<RecordingSettings>(userID, SETTINGS_COLLECTION, KEY))?.value ?? DEFAULT_SETTINGS
   }
 
-  /** Sets `enabled` when the stored revision is `expectedRevision`; a stale one answers the current revision. */
-  async set(userID: string, enabled: boolean, expectedRevision: number): Promise<SettingsWrite> {
+  /**
+   * Sets `enabled` and/or `developer` when the stored revision is `expectedRevision`; a stale one answers the current
+   * revision. Developer mode implies recording: developer on turns recording on, recording off turns developer off;
+   * a change of `enabled` alone (an older console) keeps developer as it is.
+   */
+  async set(userID: string, change: SettingsChange, expectedRevision: number): Promise<SettingsWrite> {
     for (let attempt = 0; attempt < 8; attempt++) {
       const stored = await this.state.get<RecordingSettings>(userID, SETTINGS_COLLECTION, KEY)
       const current = stored?.value ?? DEFAULT_SETTINGS
       if (current.revision !== expectedRevision) return { ok: false, currentRevision: current.revision }
-      const next: RecordingSettings = { enabled, revision: current.revision + 1, updatedAt: this.now() }
+      const developer = change.developer ?? (change.enabled === false ? false : current.developer === true)
+      const enabled = developer || (change.enabled ?? current.enabled)
+      const next: RecordingSettings = { enabled, ...(current.developer !== undefined || developer ? { developer } : {}), revision: current.revision + 1, updatedAt: this.now() }
       const written = await this.state.put(userID, SETTINGS_COLLECTION, KEY, next, { ifVersion: stored?.version ?? 0 })
-      if (written.ok) return { ok: true, settings: next, changed: current.enabled !== enabled }
+      if (written.ok) return { ok: true, settings: next, changed: current.enabled !== enabled, developerChanged: (current.developer === true) !== developer }
     }
     const current = await this.get(userID)
     return { ok: false, currentRevision: current.revision }

package/src/central/recording/store.ts

@@ -81,6 +81,19 @@ export interface AudioEntry {
   readonly redacted?: true
 }
 
+/** Developer mode: an audio clip (k) or a reply sentence's audio (r), numbered per recording. */
+export interface ExtraEntry {
+  readonly hash: string
+  readonly bytes: number
+  readonly at: number
+  /** Replies: the sentence's ref. */
+  readonly ref?: { readonly messageID: string; readonly ordinal: number; readonly seq?: number; readonly i: number }
+}
+export const clipKey = (n: number) => `k${String(n).padStart(6, "0")}`
+export const replyKey = (n: number) => `r${String(n).padStart(6, "0")}`
+/** Index keys of event pages (c…, h…); a… are segments, k… clips, r… reply audio. */
+export const isPageKey = (key: string) => key.startsWith("c") || key.startsWith("h")
+
 export const consoleKey = (firstSeq: number) => `c${String(firstSeq).padStart(10, "0")}`
 export const hubKey = (podTag: string, n: number) => `h${podTag}-${String(n).padStart(8, "0")}`
 export const audioKey = (n: number) => `a${String(n).padStart(6, "0")}`
@@ -116,6 +129,9 @@ export function summaryOf(r: RecordingRecord): RecordingSummary {
     events: r.events,
     audio: r.audio,
     redactions: r.redactions,
+    ...(r.developer ? { developer: true as const } : {}),
+    ...(r.clips ? { clips: r.clips } : {}),
+    ...(r.replies ? { replies: r.replies } : {}),
   }
 }
 
@@ -274,6 +290,8 @@ export interface StartFacts {
   readonly anchor: RecordingAnchor
   readonly audio: boolean
   readonly at: number
+  /** Developer mode was on at start. */
+  readonly developer?: boolean
 }
 
 export function newRecord(facts: StartFacts, speech: SpeechFacts): RecordingRecord {
@@ -303,6 +321,7 @@ export function newRecord(facts: StartFacts, speech: SpeechFacts): RecordingReco
     lastEventAt: facts.at,
     capNoted: [],
     skipped: { cap: 0, failed: 0 },
+    ...(facts.developer ? { developer: true as const } : {}),
     ...speech,
   }
 }

package/src/central/recording/taps.ts

@@ -10,6 +10,25 @@ export interface TapSink {
   hub(userID: string, sessionID: string, kind: HubEventKind, fields: Record<string, unknown>): void
   /** False when the user surely has no active recording (a fresh, empty cache); true when unsure. */
   mayRecord(userID: string): boolean
+  /** (Developer mode) A turn ended: its timings, for the session's developer recordings (turn.detail). */
+  turnDetail?(userID: string, sessionID: string, detail: TurnTimings): void
+}
+
+/** A turn's timings (ms from its start), for Developer mode's turn.detail. Tool names only, never their input. */
+export interface TurnTimings {
+  readonly outcome: "succeeded" | "failed" | "interrupted"
+  readonly ms: number
+  readonly firstTokenMs?: number
+  readonly tools: ReadonlyArray<{ readonly callID: string; readonly tool?: string; readonly startMs: number; readonly endMs?: number; readonly state: "called" | "success" | "failed" }>
+}
+
+/** Tool calls kept per turn in turn.detail. */
+const TURN_TOOLS_MAX = 50
+
+interface TurnTrack {
+  readonly at: number
+  firstTokenMs?: number
+  readonly tools: Map<string, { callID: string; tool?: string; startMs: number; endMs?: number; state: "called" | "success" | "failed" }>
 }
 
 const OUTCOMES: Record<string, "succeeded" | "failed" | "interrupted"> = {
@@ -34,8 +53,16 @@ export class RegistryTaps implements RecordingTap {
   private readonly firstToken = new Set<string>()
   /** Tool names by call ID (session.tool.input.started carries the name, the later events do not). */
   private readonly tools = new Map<string, string>()
+  /** (Developer mode) The running turn of each root session: its start, first token and tool calls. */
+  private readonly turns = new Map<string, TurnTrack>()
+  private readonly now: () => number
 
-  constructor(private readonly sink: TapSink) {}
+  constructor(
+    private readonly sink: TapSink,
+    now: () => number = Date.now,
+  ) {
+    this.now = now
+  }
 
   wants(tenant: string, sessionID: string, type: string): boolean {
     if (type === "session.text.delta") return this.firstToken.has(sessionID) && this.sink.mayRecord(tenant)
@@ -47,6 +74,7 @@ export class RegistryTaps implements RecordingTap {
     if (type === "session.execution.started") {
       this.firstToken.add(sessionID)
       if (this.firstToken.size > 1000) this.firstToken.delete(this.firstToken.values().next().value as string)
+      if (this.sink.turnDetail) remember(this.turns, sessionID, { at: this.now(), tools: new Map() })
       this.sink.hub(tenant, sessionID, "turn.started", {})
       return
     }
@@ -54,10 +82,17 @@ export class RegistryTaps implements RecordingTap {
     if (outcome) {
       this.firstToken.delete(sessionID)
       this.sink.hub(tenant, sessionID, "turn.ended", { outcome })
+      const track = this.turns.get(sessionID)
+      if (track) {
+        this.turns.delete(sessionID)
+        this.sink.turnDetail?.(tenant, sessionID, { outcome, ms: this.now() - track.at, ...(track.firstTokenMs !== undefined ? { firstTokenMs: track.firstTokenMs } : {}), tools: [...track.tools.values()] })
+      }
       return
     }
     if (type === "session.text.delta") {
       if (!this.firstToken.delete(sessionID)) return
+      const track = this.turns.get(sessionID)
+      if (track) track.firstTokenMs = this.now() - track.at
       const { assistantMessageID: messageID, ordinal } = data
       this.sink.hub(tenant, sessionID, "first.token", { ...(typeof messageID === "string" ? { messageID } : {}), ...(typeof ordinal === "number" ? { ordinal } : {}) })
       return
@@ -71,6 +106,15 @@ export class RegistryTaps implements RecordingTap {
     if (!state || !callID) return
     const tool = this.tools.get(callID)
     if (state !== "called") this.tools.delete(callID)
+    const track = this.turns.get(sessionID)
+    if (track) {
+      const ms = this.now() - track.at
+      const call = track.tools.get(callID)
+      if (call) {
+        call.state = state
+        if (state !== "called") call.endMs = ms
+      } else if (track.tools.size < TURN_TOOLS_MAX) track.tools.set(callID, { callID, ...(tool ? { tool } : {}), startMs: ms, ...(state !== "called" ? { endMs: ms } : {}), state })
+    }
     // The summary only (summarizeToolInput on the spoke): never the input itself, never the output or error.
     const summary = state === "called" && typeof data.summary === "string" ? data.summary : undefined
     this.sink.hub(tenant, sessionID, "tool", { callID, ...(tool ? { tool } : {}), ...(summary !== undefined ? { summary } : {}), state })

package/src/central/speech/openai.ts

@@ -1,7 +1,7 @@
 // OpenAI-compatible speech endpoints (OpenAI, Groq, local whisper/kokoro servers, ...):
 // STT as multipart POST {baseURL}/audio/transcriptions (file, model, language?), TTS as
 // POST {baseURL}/audio/speech {model, input, voice, response_format: "mp3", speed?}.
-import { audioBody, audioMime, collect, SpeechError, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider } from "./provider"
+import { audioBody, audioMime, collect, SpeechError, timedTranscription, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider, type TranscribeStats } from "./provider"
 
 export interface OpenAICompatibleOptions {
   /** Base URL including the version path, e.g. https://api.openai.com/v1 (no trailing slash). */
@@ -25,7 +25,7 @@ export class OpenAICompatible implements SpeechProvider {
     this.verbose = wantsVerbose(options.sttModel)
   }
 
-  async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): Promise<string> {
+  async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, stats?: TranscribeStats): Promise<string> {
     const headers = await this.headers()
     const send = (verbose: boolean) => {
       const form = new FormData()
@@ -36,9 +36,9 @@ export class OpenAICompatible implements SpeechProvider {
       if (verbose) form.append("response_format", "verbose_json")
       return this.fetch(`${this.options.baseURL}/audio/transcriptions`, { method: "POST", headers, body: form, signal })
     }
-    const response = await withVerboseRetry(send, this.verbose, () => (this.verbose = false))
+    const { response, json } = await timedTranscription(() => withVerboseRetry(send, this.verbose, () => (this.verbose = false)), stats)
     if (!response.ok) throw await failure("transcription", response)
-    return transcriptText(await response.json())
+    return transcriptText(await json())
   }
 
   async speak(text: string, speed?: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>> {

package/src/central/speech/openrouter.ts

@@ -1,6 +1,6 @@
 // OpenRouter speech-to-text (/audio/transcriptions as OpenAI-style multipart: the audio goes up as binary,
 // not as base64 JSON, a third smaller and no encoding) and text-to-speech (/audio/speech).
-import { audioBody, audioMime, collect, SpeechError, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider } from "./provider"
+import { audioBody, audioMime, collect, SpeechError, timedTranscription, transcriptText, upstreamDetail, wantsVerbose, withSpeedRetry, withVerboseRetry, type SpeechProvider, type TranscribeStats } from "./provider"
 
 export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
 
@@ -33,7 +33,7 @@ export class OpenRouter implements SpeechProvider {
     this.verbose = wantsVerbose(options.sttModel)
   }
 
-  async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): Promise<string> {
+  async transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, stats?: TranscribeStats): Promise<string> {
     const { sttModel: model, language } = this.options
     // OpenRouter documents multipart file/model/language (up to 25 MB; an utterance is at most ~2 MB of WAV), and
     // response_format verbose_json (segments with Whisper's no_speech_prob) for OpenAI-compatible providers.
@@ -45,9 +45,9 @@ export class OpenRouter implements SpeechProvider {
       if (verbose) form.append("response_format", "verbose_json")
       return this.post("/audio/transcriptions", form, signal)
     }
-    const response = await withVerboseRetry(send, this.verbose, () => (this.verbose = false))
+    const { response, json } = await timedTranscription(() => withVerboseRetry(send, this.verbose, () => (this.verbose = false)), stats)
     if (!response.ok) throw await failure("transcription", response)
-    return transcriptText(await response.json())
+    return transcriptText(await json())
   }
 
   async speak(text: string, speed?: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>> {

package/src/central/speech/provider.ts

@@ -1,15 +1,46 @@
 // Speech provider interface shared by OpenRouter and OpenAI-compatible endpoints, the typed upstream
 // error (mapped to 502 by the hub), audio format detection, and the speed-retry rule.
 
+/**
+ * (Recording) What a transcription's upstream request looked like, filled in by the provider when asked: the HTTP
+ * status, the response's bytes and the time to its headers (ms, from the first request: a verbose retry included).
+ */
+export interface TranscribeStats {
+  status?: number
+  bytes?: number
+  headersMs?: number
+}
+
 /** Speech-to-text and text-to-speech against one configured provider. */
 export interface SpeechProvider {
-  transcribe(audio: Uint8Array, format: string, signal?: AbortSignal): Promise<string>
+  transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, stats?: TranscribeStats): Promise<string>
   /** MP3 audio. `speed` is optional; providers that reject it get one retry without it. */
   speak(text: string, speed?: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>>
   /** The same MP3 as a stream, passed through as the provider sends it (errors are thrown before any byte). */
   speakStream(text: string, speed?: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>
 }
 
+/**
+ * Sends a transcription (`send`, with its retries) noting the status and the time to the headers in `stats`, then
+ * reads the JSON body noting its size. A failed status is returned as is (the caller turns it into its error).
+ */
+export async function timedTranscription(send: () => Promise<Response>, stats: TranscribeStats | undefined): Promise<{ response: Response; json: () => Promise<unknown> }> {
+  const started = performance.now()
+  const response = await send()
+  if (stats) {
+    stats.status = response.status
+    stats.headersMs = Math.round(performance.now() - started)
+  }
+  return {
+    response,
+    json: async () => {
+      const raw = new Uint8Array(await response.arrayBuffer())
+      if (stats) stats.bytes = raw.byteLength
+      return JSON.parse(new TextDecoder().decode(raw))
+    },
+  }
+}
+
 /** A successful upstream response's body (an empty stream when it has none). */
 export function audioBody(response: Response): ReadableStream<Uint8Array> {
   return response.body ?? new ReadableStream({ start: (controller) => controller.close() })

package/src/central/speech/service.ts

@@ -3,7 +3,7 @@
 import { OpenAICompatible } from "./openai"
 import { OpenRouter } from "./openrouter"
 import { speechModelList, withCurrent, type SpeechModelInfo, type SpeechModelList } from "./models"
-import { SpeechError, upstreamDetail, type SpeechProvider } from "./provider"
+import { SpeechError, upstreamDetail, type SpeechProvider, type TranscribeStats } from "./provider"
 import {
   lowerLayers,
   resolveStt,
@@ -34,7 +34,8 @@ export interface SpeechSettingsStore {
 
 /** Speech for one scope: a user (their settings over the default) or, without a user, the server default. */
 export interface ScopedSpeech {
-  transcribe(audio: Uint8Array, format: string): Promise<string>
+  /** `stats`: the upstream request's status, bytes and time to headers (recording mode). */
+  transcribe(audio: Uint8Array, format: string, stats?: TranscribeStats): Promise<string>
   speak(text: string): Promise<Uint8Array<ArrayBuffer>>
   /** The audio as the provider streams it; `signal` aborts the upstream request (the phone moved on). */
   speakStream(text: string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>
@@ -94,14 +95,14 @@ export class SpeechService {
   /** Speech with a user's effective settings (undefined: the server default). */
   forUser(userID: string | undefined): ScopedSpeech {
     return {
-      transcribe: (audio, format) => this.transcribe(audio, format, undefined, userID),
+      transcribe: (audio, format, stats) => this.transcribe(audio, format, undefined, userID, stats),
       speak: (text) => this.speak(text, undefined, userID),
       speakStream: (text, signal) => this.speakStream(text, signal, userID),
     }
   }
 
-  transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, userID?: string): Promise<string> {
-    return this.provider("stt", userID).transcribe(audio, format, signal)
+  transcribe(audio: Uint8Array, format: string, signal?: AbortSignal, userID?: string, stats?: TranscribeStats): Promise<string> {
+    return this.provider("stt", userID).transcribe(audio, format, signal, stats)
   }
 
   speak(text: string, signal?: AbortSignal, userID?: string): Promise<Uint8Array<ArrayBuffer>> {

package/src/central/teams/hop-stalls.ts

@@ -0,0 +1,72 @@
+// One persistent hop-cap stall per team. A reservation prevents simultaneous sends from opening two Decisions.
+import type { StateStore } from "../backend/types"
+import { updateVersioned } from "../agent/versioned"
+
+export const TEAM_HOP_STALLS = "team-hop-stalls"
+/** A hub that crashed after reserving, but before opening its Decision, may retry after this long. */
+export const TEAM_HOP_CLAIM_STALE_MS = 5 * 60_000
+
+interface Stall {
+  readonly sender: string
+  readonly recipient: string
+  readonly limit: number
+  readonly decisionID?: string
+  readonly at: number
+}
+
+export class TeamHopStalls {
+  constructor(private readonly deps: {
+    readonly state: StateStore
+    readonly seats: (userID: string, teamID: string) => Promise<readonly string[]>
+    readonly open: (userID: string, teamID: string, sender: string, recipient: string, limit: number) => Promise<string>
+    readonly notice?: (userID: string, teamID: string, decisionID: string) => Promise<void>
+    readonly close?: (userID: string, decisionID: string) => Promise<void>
+    readonly reset: (userID: string, sessionID: string) => Promise<void>
+    readonly now?: () => number
+  }) {}
+
+  async hit(userID: string, teamID: string, sender: string, recipient: string, limit: number): Promise<boolean> {
+    const previous = await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID)
+    if (previous && previous.value.decisionID === undefined && (this.deps.now ?? Date.now)() - previous.value.at >= TEAM_HOP_CLAIM_STALE_MS) {
+      // CAS: never erase an open Decision or a replacement claim made by another caller.
+      await this.deps.state.delete(userID, TEAM_HOP_STALLS, teamID, { ifVersion: previous.version })
+    }
+    const claimed = await this.deps.state.put<Stall>(userID, TEAM_HOP_STALLS, teamID, { sender, recipient, limit, at: (this.deps.now ?? Date.now)() }, { ifVersion: 0 })
+    if (!claimed.ok) return false
+    try {
+      const decisionID = await this.deps.open(userID, teamID, sender, recipient, limit)
+      await updateVersioned<Stall>(this.deps.state, userID, TEAM_HOP_STALLS, teamID, (current) => current?.sender === sender && current.recipient === recipient && current.decisionID === undefined ? { ...current, decisionID } : undefined)
+      try {
+        await this.deps.notice?.(userID, teamID, decisionID)
+      } catch (cause) {
+        // The Decision was opened and persisted; never erase it because a spoke refused a quiet notice.
+        console.error(`[hub] team hop-cap entry notice failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+      }
+      return true
+    } catch (cause) {
+      await this.deps.state.delete(userID, TEAM_HOP_STALLS, teamID, { ifVersion: claimed.version })
+      throw cause
+    }
+  }
+
+  async stalled(userID: string, teamID: string, sessionID: string): Promise<(Stall & { readonly decisionID: string }) | undefined> {
+    const stall = (await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID))?.value
+    if (!stall?.decisionID || stall.recipient !== sessionID) return undefined
+    return stall as Stall & { readonly decisionID: string }
+  }
+
+  async renew(userID: string, teamID: string, decisionID: string): Promise<void> {
+    const entry = await this.deps.state.get<Stall>(userID, TEAM_HOP_STALLS, teamID)
+    if (!entry || entry.value.decisionID !== decisionID) throw new Error("No matching team hop-cap Decision")
+    for (const sessionID of new Set(await this.deps.seats(userID, teamID))) await this.deps.reset(userID, sessionID)
+    await this.deps.state.delete(userID, TEAM_HOP_STALLS, teamID, { ifVersion: entry.version })
+  }
+
+  async clearForHuman(userID: string, sessionID: string): Promise<void> {
+    for (const { key, value, version } of await this.deps.state.list<Stall>(userID, TEAM_HOP_STALLS)) {
+      if (value.recipient !== sessionID && value.sender !== sessionID) continue
+      if (!(await this.deps.state.delete(userID, TEAM_HOP_STALLS, key, { ifVersion: version })).ok) continue
+      if (value.decisionID) await this.deps.close?.(userID, value.decisionID)
+    }
+  }
+}

package/src/central/teams/policy.ts

@@ -109,6 +109,16 @@ const sessionParty = (entry: DirectoryEntry): Party => ({ kind: "session", sessi
 export class TeamPolicy {
   constructor(private readonly deps: TeamPolicyDeps) {}
 
+  /** Shared active seat(s) only; cross-team and non-team sends use the global limit. */
+  async hopContext(userID: string, from: Party, to: Party, explicitTeamID?: string): Promise<{ teamID: string; limit?: number } | undefined> {
+    if (from.kind !== "session" || to.kind !== "session") return undefined
+    const ctx = await this.context(userID, [from.sessionID, to.sessionID])
+    const shared = seatsIn(ctx, from.sessionID).map((s) => s.teamID).filter((id) => (explicitTeamID === undefined || explicitTeamID === id) && seatsIn(ctx, to.sessionID).some((s) => s.teamID === id) && ctx.teams.get(id)?.state === "active").sort()
+    const teamID = shared[0]
+    if (!teamID) return undefined
+    return { teamID, ...(ctx.teams.get(teamID)?.hopLimit !== undefined ? { limit: ctx.teams.get(teamID)!.hopLimit } : {}) }
+  }
+
   /** Starts a send from `from` to `addr` (see the header). */
   async prepare(userID: string, from: Party, addr: string): Promise<TeamSend> {
     const resolved = await this.resolve(userID, from, addr)

package/src/central/teams/routes.ts

@@ -249,6 +249,7 @@ export function teamRoutes(deps: TeamRoutesDeps): AgentRoute[] {
       allow: MANAGE,
       async handle(context) {
         const body = await bodyOf(context.request)
+        if (body.hopLimit !== undefined && context.actor.kind !== "user") throw new AgentError("forbidden", "Only the user may set a team's hop limit")
         const key = idempotencyKeyOf(context.request)
         const { team, created } = await teams.create(context.user.id, body, key === undefined ? {} : { idempotencyKey: key })
         if (created) await changed(context, "team.create", team.id, teamCreatedEvent(team))
@@ -292,6 +293,7 @@ export function teamRoutes(deps: TeamRoutesDeps): AgentRoute[] {
       allow: MANAGE,
       async handle(context) {
         const { expectedRevision, publish, ...patch } = await bodyOf(context.request)
+        if (patch.hopLimit !== undefined && context.actor.kind !== "user") throw new AgentError("forbidden", "Only the user may set a team's hop limit")
         if (publish !== undefined && typeof publish !== "boolean") throw new AgentError("invalid", "publish must be true or false")
         const revision = expected(expectedRevision)
         const { id } = await managed(context)

package/src/central/teams/seats.ts

@@ -47,7 +47,7 @@ export interface TeamSeatRecord extends TeamStaffing {
   readonly teamVersion: number
 }
 
-export type DeliveryTeams = ReadonlyMap<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state">>
+export type DeliveryTeams = ReadonlyMap<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state" | "hopLimit">>
 
 export interface DeliveryContext {
   /** Each asked session's current seats (empty when it holds none). */
@@ -199,11 +199,11 @@ export class TeamSeatStore {
   /** Seats of several sessions and the teams they are in: teamDeliveryVerdict's inputs (HWA-34). */
   async deliveryContext(userID: string, sessionIDs: readonly string[]): Promise<DeliveryContext> {
     const seats = await this.seatsBySession(userID, sessionIDs)
-    const teams = new Map<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state">>()
+    const teams = new Map<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state" | "hopLimit">>()
     for (const teamID of new Set([...seats.values()].flat().map((s) => s.teamID))) {
       try {
         const team = await this.teams.get(userID, teamID)
-        if (team) teams.set(teamID, { mode: team.mode, edges: team.edges, roles: team.roles, state: team.state })
+        if (team) teams.set(teamID, { mode: team.mode, edges: team.edges, roles: team.roles, state: team.state, ...(team.hopLimit !== undefined ? { hopLimit: team.hopLimit } : {}) })
       } catch {
         // A team this build cannot read takes no part in delivery (its seats are then ignored by the verdict).
       }

package/src/central/teams/staffing.ts

@@ -75,6 +75,7 @@ import { readSeatsDoc, type SeatsDoc, TEAM_SEATS } from "./collections"
 import { teamStaffedEvent, teamUnstaffedEvent } from "./events"
 import type { TeamSeatRecord, TeamSeatStore } from "./seats"
 import type { Team, TeamStore } from "./store"
+import type { TeamHopStalls } from "./hop-stalls"
 import { TEAM_STORE_LIMITS, type TeamRoleSpec } from "./validation"
 
 /** One aggregate per team (key: team ID): workspace link, managed members, launch requests, Idempotency-Keys. */
@@ -144,6 +145,8 @@ export interface SeatProfileStatus {
 export interface RosterSeat {
   readonly staffing: TeamSeatRecord
   readonly presence: SessionPresence
+  /** An agent-only message to this seat hit the team's hop limit; only the user may renew. */
+  readonly stalled?: "hop cap"
   readonly memberID?: string
   readonly supervisorMemberID?: string
   readonly profile?: SeatProfileStatus
@@ -208,6 +211,7 @@ export interface TeamStaffingDeps {
   readonly members: MembershipStore
   readonly supervision: SupervisionStore
   readonly presence: SessionPresenceLookup
+  readonly hopStalls?: Pick<TeamHopStalls, "stalled">
   /** The session's project directory now (grant scope); undefined when no spoke reports it. */
   readonly sessionDirectory: (userID: string, sessionID: string) => string | undefined
   readonly launches: Pick<LaunchEngine, "accept" | "view">
@@ -454,6 +458,7 @@ export class TeamStaffingService {
         seats.push({
           staffing,
           presence: presence.get(staffing.sessionID)!,
+          ...(await this.deps.hopStalls?.stalled(userID, teamID, staffing.sessionID) ? { stalled: "hop cap" as const } : {}),
           ...(memberID !== undefined ? { memberID } : {}),
           ...(supervisorMemberID !== undefined ? { supervisorMemberID } : {}),
           ...(profile ? { profile } : {}),

package/src/central/teams/store.ts

@@ -132,6 +132,7 @@ export type PinnedVersions = (userID: string, teamID: string) => Promise<Readonl
 
 export interface TeamStoreDeps {
   readonly state: StateStore
+  readonly globalHopLimit?: number
   readonly now?: Clock
   readonly newID?: (kind: IdKind) => string
   readonly limits?: Partial<TeamStoreLimits>
@@ -256,12 +257,14 @@ export class TeamStore {
   private readonly now: Clock
   private readonly newID: (kind: IdKind) => string
   private readonly pinned?: PinnedVersions
+  private readonly globalHopLimit: number
 
   constructor(deps: TeamStoreDeps) {
     this.state = deps.state
     this.now = deps.now ?? Date.now
     this.newID = deps.newID ?? ((kind) => `${ID_PREFIXES[kind]}_${randomBytes(12).toString("hex")}`)
     this.pinned = deps.pinnedVersions
+    this.globalHopLimit = deps.globalHopLimit ?? 8
     this.limits = {
       teamsPerUser: deps.limits?.teamsPerUser ?? TEAM_LIMITS.teamsPerUser,
       versionsRetained: deps.limits?.versionsRetained ?? TEAM_STORE_LIMITS.versionsRetained,
@@ -277,7 +280,7 @@ export class TeamStore {
    * another body is a conflict.
    */
   async create(userID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<{ team: Team; created: boolean }> {
-    const spec = teamSpecOf(input)
+    const spec = teamSpecOf(input, this.globalHopLimit)
     const key = options.idempotencyKey
     if (key === undefined) return { team: await this.insert(userID, this.newID("team"), spec), created: true }
     if (!IDEMPOTENCY_KEY.test(key)) throw new AgentError("invalid", "Idempotency-Key must be 1–200 of A-Z a-z 0-9 _ . : -")
@@ -365,7 +368,7 @@ export class TeamStore {
     const expected = checkExpected(expectedRevision)
     return this.mutate(userID, id, expected, (record) => {
       this.active(record)
-      const spec = teamPatchOf(record.draft?.spec ?? record.spec, patch)
+      const spec = teamPatchOf(record.draft?.spec ?? record.spec, patch, this.globalHopLimit)
       return { ...record, draft: { baseVersion: record.version, spec, digest: specDigest(spec), savedAt: this.now() } }
     })
   }

package/src/central/teams/validation.ts

@@ -63,6 +63,7 @@ export interface TeamSpec {
   readonly title: string
   readonly description?: string
   readonly mode: TeamMode
+  readonly hopLimit?: number
   readonly roles: readonly TeamRoleSpec[]
   readonly entryRole: string
   readonly edges: readonly TeamEdge[]
@@ -82,13 +83,13 @@ export interface TeamDiff {
   readonly projects: { readonly added: readonly string[]; readonly removed: readonly string[] }
 }
 
-export const SPEC_FIELDS: ReadonlySet<string> = new Set(["name", "title", "description", "mode", "roles", "entryRole", "edges", "tags", "metadata", "projects"])
+export const SPEC_FIELDS: ReadonlySet<string> = new Set(["name", "title", "description", "mode", "hopLimit", "roles", "entryRole", "edges", "tags", "metadata", "projects"])
 const ROLE_FIELDS = new Set(["name", "label", "description", "externalContact", "responsibilities", "profile", "prefs", "minMembers", "maxMembers"])
 const EDGE_FIELDS = new Set(["from", "to", "kinds", "direction"])
 const PROFILE_FIELDS = new Set(["profileID", "version"])
 const PREFS_FIELDS = new Set(["harness", "model", "machineID"])
 const REQUIRED = new Set(["title", "mode", "roles", "entryRole"])
-const SCALARS = ["title", "description", "mode", "entryRole"] as const
+const SCALARS = ["title", "description", "mode", "entryRole", "hopLimit"] as const
 
 const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
 const fail = (message: string): never => {
@@ -157,13 +158,14 @@ function normalizedRole(r: Record<string, unknown>): TeamRoleSpec {
 }
 
 /** A validated, normalized team spec; throws AgentError invalid. */
-export function teamSpecOf(input: unknown): TeamSpec {
+export function teamSpecOf(input: unknown, globalHopLimit = 8): TeamSpec {
   if (!isObj(input)) return fail("body must be an object")
   onlyFields(input, SPEC_FIELDS, "")
   if (Array.isArray(input.roles)) for (const role of input.roles) if (isObj(role)) onlyFields(role, ROLE_FIELDS, `role ${printable(String(role.name))}: `)
   if (Array.isArray(input.edges)) for (const edge of input.edges) if (isObj(edge)) onlyFields(edge, EDGE_FIELDS, "edge: ")
   const problem = teamInputProblem(input)
   if (problem) fail(problem)
+  if (input.hopLimit !== undefined && (input.hopLimit as number) > globalHopLimit) fail(`hopLimit must not exceed the global agents.hopLimit (${globalHopLimit})`)
   const roles = input.roles as Record<string, unknown>[]
   for (const role of roles) {
     const p = roleProblem(role)
@@ -193,6 +195,7 @@ export function teamSpecOf(input: unknown): TeamSpec {
     title: input.title as string,
     ...(input.description !== undefined ? { description: input.description as string } : {}),
     mode: input.mode as TeamMode,
+    ...(input.hopLimit !== undefined ? { hopLimit: input.hopLimit as number } : {}),
     roles: roles.map(normalizedRole),
     entryRole: input.entryRole as string,
     edges,
@@ -206,7 +209,7 @@ export function teamSpecOf(input: unknown): TeamSpec {
  * The spec after a patch: fields replace the base's (roles and edges wholesale), null clears an optional one, the
  * name never changes (it is the `#team` address), and the result is validated as a whole.
  */
-export function teamPatchOf(base: TeamSpec, patch: unknown): TeamSpec {
+export function teamPatchOf(base: TeamSpec, patch: unknown, globalHopLimit = 8): TeamSpec {
   if (!isObj(patch)) return fail("body must be an object")
   onlyFields(patch, SPEC_FIELDS, "")
   const keys = Object.keys(patch)
@@ -221,7 +224,7 @@ export function teamPatchOf(base: TeamSpec, patch: unknown): TeamSpec {
       else delete next[key]
     } else if (value !== undefined) next[key] = value
   }
-  return teamSpecOf(next)
+  return teamSpecOf(next, globalHopLimit)
 }
 
 /** sha256 of the spec's canonical JSON (key order never matters). */

package/src/spoke/spoke.ts

@@ -28,6 +28,7 @@ import {
   type SessionTokensRequest,
   type ActTokensRequest,
   type CreateRequest,
+  type ModelSelection,
   type SessionModelPrefs,
   type SpokeRequest,
   type TerminalInfo,
@@ -1419,6 +1420,8 @@ export class Spoke {
         else this.modelPrefs.delete(req.sessionID)
         return this.modelPrefsResult(req.sessionID)
       }
+      case "setModel":
+        return this.setSessionModel(req.sessionID, req.model)
       case "timeline": {
         // A first page reads OpenCode (it shows the newest state); following pages reuse those rows briefly. A
         // staged revert hides its message and everything after it (OpenCode keeps them until it is committed).
@@ -1940,6 +1943,22 @@ export class Spoke {
     await this.host.switchModel(sessionID, model)
   }
 
+  /**
+   * (feature "setModel") The session's own model, as the console picked it: OpenCode's session.switchModel stores it
+   * on the session, so every later turn runs on it whoever prompts (the console, the TUI, a voice relay). Only a
+   * model (and variant) of this OpenCode's catalog; no variant: the model's default.
+   */
+  private async setSessionModel(sessionID: string, model: ModelSelection): Promise<ResultFor["setModel"]> {
+    const catalog = (await this.host.listModels?.()) ?? []
+    const known = catalog.find((value: any) => value?.providerID === model.providerID && (typeof value.id === "string" && value.id ? value.id : value.modelID) === model.modelID) as any
+    const variants: string[] = Array.isArray(known?.variants) ? known.variants.flatMap((v: any) => (typeof v?.id === "string" ? [v.id] : [])) : []
+    const variant = model.variant && model.variant !== "default" ? model.variant : undefined
+    if (!known || (variant && !variants.includes(variant))) throw new Error(`Unknown model ${model.providerID}/${model.modelID}${variant ? `#${variant}` : ""} for this session`)
+    const ref: ModelRef = { providerID: model.providerID, id: model.modelID, ...(variant ? { variant } : {}) }
+    await this.switchModel(sessionID, ref)
+    return { model: sessionModel({ chosen: ref, models: catalog })! }
+  }
+
   /** Enables or disables voice for a session this process reported (mode "session" only). */
   private expose(sessionID: string, on: boolean): ResultFor["expose"] {
     if (!this.tracker.has(sessionID)) throw new Error("Unknown session")

package/web/dist/assets/{ArtifactPage-Bz992ZX6.js → ArtifactPage-C5MMqXLN.js}

@@ -1 +1 @@
-import{B as e,I as t,S as n,i as r,k as i,r as a}from"./ui-CFB4wQfF.js";import{o}from"./artifacts-But87Jfo.js";import{it as s,rt as c}from"./index-BS6lA6fN.js";import{t as l}from"./ArtifactWorkbench-Dti3VP07.js";var u=i(`<div class="feature-page av-page">`),d=i(`<a class="icon-btn av-back"href=/artifacts aria-label="All artifacts"title="All artifacts">`);function f(i){return(()=>{var f=u();return n(f,e(l,{get id(){return i.id},layout:`page`,get lead(){return[e(t,{get when(){return c()},get children(){return e(r,{icon:`menu`,label:`Open sidebar`,onClick:s})}}),(()=>{var t=d();return n(t,e(a,{name:`back`})),t})()]},get actions(){return e(r,{class:`av-wide`,icon:`split`,label:`Open in pane`,onClick:()=>o(i.id)})}})),f})()}export{f as default};
+import{B as e,I as t,S as n,i as r,k as i,r as a}from"./ui-CFB4wQfF.js";import{o}from"./artifacts-DlQEYmDl.js";import{it as s,rt as c}from"./index-Da8SKXMw.js";import{t as l}from"./ArtifactWorkbench-S0RxNGWy.js";var u=i(`<div class="feature-page av-page">`),d=i(`<a class="icon-btn av-back"href=/artifacts aria-label="All artifacts"title="All artifacts">`);function f(i){return(()=>{var f=u();return n(f,e(l,{get id(){return i.id},layout:`page`,get lead(){return[e(t,{get when(){return c()},get children(){return e(r,{icon:`menu`,label:`Open sidebar`,onClick:s})}}),(()=>{var t=d();return n(t,e(a,{name:`back`})),t})()]},get actions(){return e(r,{class:`av-wide`,icon:`split`,label:`Open in pane`,onClick:()=>o(i.id)})}})),f})()}export{f as default};