@huynle/hub 0.7.1 → 0.7.3

package/packages/protocol/src/index.ts

@@ -91,7 +91,7 @@ export interface TimelinePage {
 }
 
 /** Timeline row kinds. "message": a hub message (src/spoke/timeline.ts has the others). */
-export const TIMELINE_KINDS = ["user", "assistant", "reasoning", "tool", "message"] as const
+export const TIMELINE_KINDS = ["user", "assistant", "reasoning", "tool", "message", "error", "retry"] as const
 export type TimelineKind = (typeof TIMELINE_KINDS)[number]
 
 /** A message row's direction from the session's point of view: delivered to it (in) or sent by it (out). */
@@ -230,15 +230,21 @@ export interface InboxDeliveredData {
 }
 
 /**
- * OpenCode events the spoke forwards only in another (compact) form: a subagent tool's progress, which names the
- * child session, goes out as a `session.tool.called` with `childSessionID` (a type every hub accepts).
+ * OpenCode events the spoke forwards only in another (compact) form, as a type every hub accepts: a subagent tool's
+ * progress, which names the child session, goes out as a `session.tool.called` with `childSessionID`; a scheduled
+ * retry (OpenCode 2.2 publishes no session.status) goes out as a `session.status` of type retry. Never add these to
+ * FORWARDED_EVENTS: older hubs close the connection on an event type they do not know.
  */
-export const COMPACTED_EVENTS: ReadonlySet<string> = new Set(["session.tool.progress"])
+export const COMPACTED_EVENTS: ReadonlySet<string> = new Set(["session.tool.progress", "session.retry.scheduled"])
 
 /** Longest job command forwarded. */
 export const JOB_COMMAND_MAX = 200
 /** Longest retry reason forwarded. */
 export const RETRY_MESSAGE_MAX = 200
+/** Longest run error message forwarded (session.execution.failed; as HARNESS_ERROR_MAX). */
+export const ERROR_MESSAGE_MAX = 1000
+/** Longest error type forwarded (e.g. "provider.quota"). */
+export const ERROR_TYPE_MAX = 64
 /** Most running jobs one seed event carries. */
 export const SEED_JOBS_MAX = 20
 
@@ -258,7 +264,27 @@ export interface JobInfo {
 }
 
 /** OpenCode's session status, compact. */
-export type CompactSessionStatus = { readonly type: "idle" | "busy" } | { readonly type: "retry"; readonly attempt?: number; readonly message?: string }
+export type CompactSessionStatus =
+  | { readonly type: "idle" | "busy" }
+  | {
+      readonly type: "retry"
+      readonly attempt?: number
+      /** Why it retries (the error's message, ≤ RETRY_MESSAGE_MAX). */
+      readonly message?: string
+      /** When the next attempt runs (epoch ms). */
+      readonly next?: number
+      /** The error's type, e.g. "provider.rate-limit" (≤ ERROR_TYPE_MAX). */
+      readonly errorType?: string
+      /** The error's HTTP status (100–599). */
+      readonly errorStatus?: number
+    }
+
+/** A run's error as forwarded (session.execution.failed, and a seed's last failure): no response body. */
+export interface CompactRunError {
+  readonly message: string
+  readonly type?: string
+  readonly status?: number
+}
 
 // ---------- spoke → server ----------
 
@@ -1097,6 +1123,7 @@ export function summarizeToolInput(input: unknown): string {
 export function compactActivity(event: ForwardedEvent, sessionOf?: (jobID: string) => string | undefined, now: number = Date.now()): ForwardedEvent | undefined {
   const d = event.data
   if (JOB_EVENTS.has(event.type) || event.type === "session.status") return compactJob(event, sessionOf, now)
+  if (event.type === "session.retry.scheduled") return compactRetry(d)
   const base = { sessionID: d.sessionID, assistantMessageID: d.assistantMessageID, id: d.id }
   switch (event.type) {
     case "session.tool.input.started":
@@ -1115,6 +1142,11 @@ export function compactActivity(event: ForwardedEvent, sessionOf?: (jobID: strin
       const message = typeof (d.error as any)?.message === "string" ? String((d.error as any).message).slice(0, ACTIVITY_SUMMARY_MAX) : "failed"
       return { type: event.type, data: { ...base, error: message } }
     }
+    case "session.execution.failed":
+      return {
+        type: event.type,
+        data: { sessionID: d.sessionID, ...(typeof d.turnID === "string" && d.turnID ? { turnID: d.turnID } : {}), error: compactRunError(d.error) ?? { message: "failed" } },
+      }
     case "session.reasoning.started":
     case "session.reasoning.ended":
       return { type: event.type, data: { sessionID: d.sessionID, assistantMessageID: d.assistantMessageID } }
@@ -1146,7 +1178,10 @@ function clipText(value: unknown, max: number): string | undefined {
 
 const finite = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined)
 
-/** OpenCode's SessionStatus reduced to its type and (retry) attempt and short reason. */
+const errorType = (v: unknown): string | undefined => (typeof v === "string" && v.length > 0 && v.length <= ERROR_TYPE_MAX ? v : undefined)
+const httpStatus = (v: unknown): number | undefined => (Number.isInteger(v) && (v as number) >= 100 && (v as number) <= 599 ? (v as number) : undefined)
+
+/** OpenCode's SessionStatus reduced to its type and (retry) attempt, short reason, next try and error kind. */
 export function compactStatus(raw: unknown): CompactSessionStatus | undefined {
   const status = raw as Record<string, unknown> | null
   if (!status || typeof status !== "object") return undefined
@@ -1154,7 +1189,35 @@ export function compactStatus(raw: unknown): CompactSessionStatus | undefined {
   if (status.type !== "retry") return undefined
   const attempt = finite(status.attempt)
   const message = clipText(status.message, RETRY_MESSAGE_MAX)
-  return { type: "retry", ...(attempt !== undefined ? { attempt } : {}), ...(message ? { message } : {}) }
+  const next = finite(status.next)
+  const type = errorType(status.errorType)
+  const code = httpStatus(status.errorStatus)
+  return {
+    type: "retry",
+    ...(attempt !== undefined ? { attempt } : {}),
+    ...(message ? { message } : {}),
+    ...(next !== undefined ? { next } : {}),
+    ...(type ? { errorType: type } : {}),
+    ...(code !== undefined ? { errorStatus: code } : {}),
+  }
+}
+
+/** An OpenCode run error ({type, message, status?, response?, retryAfterMs?}) as its message, type and status only. */
+export function compactRunError(raw: unknown): CompactRunError | undefined {
+  const error = raw as Record<string, unknown> | null
+  if (!error || typeof error !== "object") return undefined
+  const message = typeof error.message === "string" && error.message.trim() ? error.message.trim().slice(0, ERROR_MESSAGE_MAX) : "failed"
+  const type = errorType(error.type)
+  const status = httpStatus(error.status)
+  return { message, ...(type ? { type } : {}), ...(status !== undefined ? { status } : {}) }
+}
+
+/** OpenCode 2.2's session.retry.scheduled as the session.status retry every hub accepts. */
+function compactRetry(d: Record<string, unknown>): ForwardedEvent | undefined {
+  if (typeof d.sessionID !== "string" || !d.sessionID) return undefined
+  const error = (d.error && typeof d.error === "object" ? d.error : {}) as Record<string, unknown>
+  const status = compactStatus({ type: "retry", attempt: d.attempt, message: error.message, next: d.at, errorType: error.type, errorStatus: error.status })
+  return { type: "session.status", data: { sessionID: d.sessionID, status } }
 }
 
 /** A ShellInfo or Pty (OpenCode) as a JobInfo. */

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/src/client.ts

@@ -5,6 +5,9 @@ import { sseEvents } from "./sse.ts"
 import type {
   Approved,
   AppTokenView,
+  Archived,
+  ArchiveInactivePreview,
+  ArchiveInactiveResult,
   Asked,
   CreatedAppToken,
   Decision,
@@ -30,6 +33,7 @@ import type {
   Named,
   PromptDelivery,
   Prompted,
+  Pinned,
   Replied,
   RoleClaim,
   RoleRelease,
@@ -40,7 +44,10 @@ import type {
   Status,
   Stopped,
   WatchEvent,
+  EventsPage,
   Whoami,
+  WebhookDelivery,
+  WebhookView,
 } from "./types.ts"
 
 const AGENT = "/api/agent"
@@ -296,15 +303,16 @@ export class HubClient {
   }
 
   /**
-   * GET /api/agent/watch: the events (session.*, blocker.*, …) as they happen, until the hub closes the stream or
-   * `signal` aborts (which ends the iteration quietly). blocked: only blocker events; session: one address.
+   * GET /api/agent/watch: the journal's compact events (the same as events()) as they happen, until the hub closes
+   * the stream or `signal` aborts (which ends the iteration quietly). blocked: only blocker events; session: one
+   * address; cursor: resume after an event's `id` (or an events() cursor).
    */
-  async *watch(options: CallOptions & { readonly blocked?: boolean; readonly session?: string } = {}): AsyncGenerator<WatchEvent, void, undefined> {
+  async *watch(options: CallOptions & { readonly blocked?: boolean; readonly session?: string; readonly cursor?: string } = {}): AsyncGenerator<WatchEvent, void, undefined> {
     const { signal } = options
     if (signal?.aborted) return
     let response: Response
     try {
-      response = await this.request("GET", `${AGENT}/watch`, { query: { blocked: options.blocked ? "1" : undefined, session: options.session }, ...signalOf(options) })
+      response = await this.request("GET", `${AGENT}/watch`, { query: { blocked: options.blocked ? "1" : undefined, session: options.session, cursor: options.cursor }, ...signalOf(options) })
     } catch (cause) {
       if (signal?.aborted) return
       throw cause
@@ -312,6 +320,49 @@ export class HubClient {
     yield* sseEvents(response, signal)
   }
 
+  /**
+   * GET /api/agent/events: the compact events after `cursor` (none: start at the latest). wait: seconds (0–60) to
+   * hold while nothing matches; limit 1–200; types (exact, or `launch.*`) and sessions filter but still advance the
+   * cursor. App tokens need events:subscribe plus each family's scope.
+   */
+  events(options: CallOptions & { readonly cursor?: string; readonly wait?: number; readonly limit?: number; readonly types?: readonly string[]; readonly sessions?: readonly string[] } = {}): Promise<EventsPage> {
+    return this.call("GET", `${AGENT}/events`, { query: { cursor: options.cursor, wait: options.wait, limit: options.limit, type: options.types, session: options.sessions }, ...signalOf(options) })
+  }
+
+  webhookCreate(input: { readonly url: string; readonly events?: readonly string[]; readonly label?: string }, options: CallOptions = {}): Promise<{ webhook: WebhookView; secret: string }> {
+    return this.call("POST", `${AGENT}/webhooks`, { body: input, ...signalOf(options) })
+  }
+
+  webhooks(options: CallOptions = {}): Promise<{ webhooks: WebhookView[] }> {
+    return this.call("GET", `${AGENT}/webhooks`, signalOf(options))
+  }
+
+  webhook(id: string, options: CallOptions = {}): Promise<{ webhook: WebhookView; deliveries: WebhookDelivery[] }> {
+    return this.call("GET", `${AGENT}/webhooks/${segment(id)}`, signalOf(options))
+  }
+
+  webhookDelete(id: string, options: CallOptions = {}): Promise<void> {
+    return this.call("DELETE", `${AGENT}/webhooks/${segment(id)}`, signalOf(options))
+  }
+
+  // Organization (sessions:manage).
+
+  setArchived(addr: string, archived: boolean, options: CallOptions = {}): Promise<Archived> {
+    return this.call("PUT", `${AGENT}/sessions/${segment(addr)}/archive`, { body: { archived }, ...signalOf(options) })
+  }
+
+  setPinned(addr: string, pinned: boolean, options: CallOptions = {}): Promise<Pinned> {
+    return this.call("PUT", `${AGENT}/sessions/${segment(addr)}/pin`, { body: { pinned }, ...signalOf(options) })
+  }
+
+  previewArchiveInactive(inactiveFor: string, limit: number, options: CallOptions = {}): Promise<ArchiveInactivePreview> {
+    return this.call("POST", `${AGENT}/sessions/archive-inactive`, { body: { preview: true, inactiveFor, limit }, ...signalOf(options) })
+  }
+
+  archiveInactive(previewToken: string, options: CallOptions = {}): Promise<ArchiveInactiveResult> {
+    return this.call("POST", `${AGENT}/sessions/archive-inactive`, { body: { previewToken, confirm: true }, ...signalOf(options) })
+  }
+
   // Naming.
 
   name(name: string, options: TargetOptions = {}): Promise<Named> {

package/packages/sdk/src/errors.ts

@@ -6,6 +6,7 @@ import type { Evaluation } from "./types.ts"
 /** The codes the hub answers with (src/central/agent/errors.ts); later phases may add more, so any string is kept. */
 export type ErrorCode =
   | "invalid"
+  | "invalid_cursor"
   | "unauthorized"
   | "token_expired"
   | "needs_user"

package/packages/sdk/src/sse.ts

@@ -5,6 +5,8 @@ import type { WatchEvent } from "./types.ts"
 /** Parses SSE text incrementally: feed chunks, get complete events (events without data are skipped). */
 export class SseParser {
   #buffer = ""
+  /** The last `id:` seen (it carries over to later events, as in EventSource). */
+  #id = ""
 
   push(chunk: string): WatchEvent[] {
     this.#buffer += chunk.replace(/\r\n?/g, "\n")
@@ -22,8 +24,9 @@ export class SseParser {
         const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "")
         if (field === "event") event = value
         else if (field === "data") data.push(value)
+        else if (field === "id" && !value.includes("\0")) this.#id = value
       }
-      if (data.length) out.push({ event, data: data.join("\n") })
+      if (data.length) out.push({ event, data: data.join("\n"), ...(this.#id ? { id: this.#id } : {}) })
     }
     return out
   }

package/packages/sdk/src/types.ts

@@ -121,6 +121,43 @@ export interface DirectoryEntry {
   readonly roles: readonly RoleView[]
 }
 
+/** One compact event of GET /api/agent/events (no free text). Unknown types are valid: ignore them. */
+export interface AgentEvent {
+  readonly id: string
+  readonly at: number
+  readonly type: string
+  readonly subject: Readonly<Record<string, string>>
+  readonly data: Readonly<Record<string, string | number | boolean>>
+}
+
+/**
+ * A page of GET /api/agent/events: pass `cursor` to the next call. `more`: records remain unread. `reset`: the
+ * cursor was no longer covered (expired, trimmed, hub restarted); re-read the `refresh` snapshots, then go on.
+ */
+export interface EventsPage {
+  readonly events: AgentEvent[]
+  readonly cursor: string
+  readonly more: boolean
+  readonly reset: boolean
+  readonly refresh?: string[]
+}
+
+export interface Archived {
+  readonly sessionID: string
+  readonly archived: boolean
+  readonly changed: boolean
+}
+
+export interface Pinned {
+  readonly sessionID: string
+  readonly pinned: boolean
+  readonly changed: boolean
+}
+
+export type ArchiveSkipReason = "active" | "pinned" | "open" | "archived" | "not_found"
+export interface ArchiveInactivePreview { readonly candidates: readonly string[]; readonly previewToken: string; readonly expiresAt: number }
+export interface ArchiveInactiveResult { readonly changed: readonly string[]; readonly skipped: readonly { readonly sessionID: string; readonly reason: ArchiveSkipReason }[] }
+
 export interface Named {
   readonly sessionID: string
   readonly name: string
@@ -271,6 +308,8 @@ export interface Inbox {
 export interface WatchEvent {
   readonly event: string
   readonly data: string
+  /** The stream's cursor at this event (GET /api/agent/watch?cursor= resumes after it). */
+  readonly id?: string
 }
 
 // Acting (POST /api/agent/sessions/:addr/{approve,deny,answer,prompt,stop}; src/central/agent/acting.ts).
@@ -430,6 +469,26 @@ export interface LaunchArtifacts {
   readonly dirty?: boolean
 }
 
+export interface WebhookView {
+  readonly id: string
+  readonly url: string
+  readonly events: readonly string[]
+  readonly by: string
+  readonly label?: string
+  readonly created: number
+}
+
+export interface WebhookDelivery {
+  readonly id: string
+  readonly event: string
+  readonly type: string
+  readonly state: "pending" | "delivered" | "failed"
+  readonly attempts: number
+  readonly created: number
+  readonly nextAt?: number
+  readonly last?: { readonly at: number; readonly status?: number; readonly error?: string }
+}
+
 /** A launch as the hub reports it (the spec with its defaults filled in). */
 export interface LaunchView {
   readonly id: string

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/spoke-sdk/src/enroll.ts

@@ -10,19 +10,40 @@ export interface EnrollOptions {
   readonly signal?: AbortSignal
   readonly fetch?: typeof fetch
   readonly now?: () => number
+  /**
+   * "follow" (default) follows HTTP redirects. "error" refuses them: a redirect could send the device code to
+   * another origin or downgrade to plain http. A refused redirect throws EnrollmentRefused, which polling does not
+   * retry.
+   */
+  readonly redirect?: "follow" | "error"
+  /**
+   * The hub hands out an approved credential exactly once. With keepRedeemed, `signal` never aborts a poll request
+   * in flight (its reply may carry that credential); it still stops polling before the next request.
+   */
+  readonly keepRedeemed?: boolean
+}
+
+/** The hub answered in a way the caller's policy refuses (a redirect under redirect: "error"); not retried. */
+export class EnrollmentRefused extends Error {
+  override readonly name = "EnrollmentRefused"
 }
 
 const REQUEST_TIMEOUT_MS = 15_000
 
-async function post(server: string, path: string, body: unknown, options: EnrollOptions): Promise<unknown> {
+async function post(server: string, path: string, body: unknown, options: EnrollOptions, abortable = true): Promise<unknown> {
   const doFetch = options.fetch ?? fetch
-  const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS), ...(options.signal ? [options.signal] : [])]
+  const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS), ...(options.signal && abortable ? [options.signal] : [])]
+  const strict = options.redirect === "error"
   const response = await doFetch(`${server.replace(/\/+$/, "")}${path}`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify(body),
     signal: AbortSignal.any(signals),
+    ...(strict ? { redirect: "manual" as const } : {}),
   })
+  if (strict && (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400))) {
+    throw new EnrollmentRefused(`${path} was redirected; enrollment does not follow redirects`)
+  }
   if (!response.ok) throw new Error(`${path} failed: HTTP ${response.status}`)
   return response.json()
 }
@@ -67,8 +88,9 @@ export async function pollEnrollment(server: string, start: EnrollStart, options
     if (options.signal?.aborted) return { status: "cancelled" }
     let reply: Partial<EnrollPoll> & Record<string, unknown>
     try {
-      reply = (await post(server, "/spoke/enroll/poll", { deviceCode: start.deviceCode }, options)) as typeof reply
-    } catch {
+      reply = (await post(server, "/spoke/enroll/poll", { deviceCode: start.deviceCode }, options, !options.keepRedeemed)) as typeof reply
+    } catch (cause) {
+      if (cause instanceof EnrollmentRefused) throw cause
       continue
     }
     if (reply?.status === "approved" && typeof reply.machineID === "string" && typeof reply.machineToken === "string") {

package/src/central/agent/app-tokens.ts

@@ -19,8 +19,10 @@ import type { AgentRoute } from "./routes"
  * acting on sessions (approve, deny, answer, prompt, stop) and launching sessions (phase 4), each of which still
  * needs a grant held by the token (with the act verb, or `launch` covering the repo).
  */
-export const APP_SCOPES: readonly string[] = ["sessions:read", "messages:send", "messages:read", "sessions:act", "sessions:launch"]
+export const APP_SCOPES: readonly string[] = ["sessions:read", "sessions:manage", "messages:send", "messages:read", "sessions:act", "sessions:launch", "events:subscribe"]
 export const DEFAULT_APP_SCOPES: readonly string[] = ["sessions:read"]
+/** What `hub login` (the CLI login device code) asks for unless it asks for more: reading sessions and messaging. */
+export const DEFAULT_CLI_LOGIN_SCOPES: readonly string[] = ["sessions:read", "messages:send", "messages:read"]
 export const MAX_APP_TOKENS = 50
 export const MAX_APP_TOKEN_LABEL = 100
 
@@ -88,6 +90,29 @@ const view = (token: AppToken) => ({
   ...(typeof token.created === "number" ? { created: token.created } : {}),
 })
 
+/**
+ * Issues an app token of `userID` (the POST route below, and an approved CLI login): the record stored (sha256 of the
+ * token only) and the token, which the caller hands out once and never logs. rate_limited at MAX_APP_TOKENS.
+ */
+export async function issueAppToken(store: Store, userID: string, input: { readonly label?: string; readonly scopes: readonly string[] }): Promise<{ record: AppToken; token: string }> {
+  const id = randomBytes(8).toString("hex")
+  const token = `hat_${id}_${randomBytes(32).toString("base64url")}`
+  const record: AppToken = { id, tokenHash: hashToken(token), ...(input.label ? { label: input.label } : {}), scopes: [...input.scopes], created: Date.now() }
+  let full = false
+  await store.updateAgentData(userID, (data) => {
+    const tokens = data.appTokens ?? []
+    full = false
+    if (tokens.length >= MAX_APP_TOKENS) {
+      full = true
+      return
+    }
+    data.appTokens = [...tokens, record]
+  })
+  if (full) throw new AgentError("rate_limited", `At most ${MAX_APP_TOKENS} app tokens per user`, { hint: "Revoke unused tokens" })
+  await store.audit({ actor: userID, action: "app-token.create", target: id, ...(input.label ? { detail: input.label } : {}) })
+  return { record, token }
+}
+
 /** POST, GET and DELETE /api/agent/app-tokens: user actors only. */
 export function appTokenRoutes(store: Store): AgentRoute[] {
   return [
@@ -96,22 +121,7 @@ export function appTokenRoutes(store: Store): AgentRoute[] {
       path: PREFIX,
       allow: {},
       async handle({ request, user }) {
-        const input = parseCreate(await request.json())
-        const id = randomBytes(8).toString("hex")
-        const token = `hat_${id}_${randomBytes(32).toString("base64url")}`
-        const record: AppToken = { id, tokenHash: hashToken(token), ...(input.label ? { label: input.label } : {}), scopes: input.scopes, created: Date.now() }
-        let full = false
-        await store.updateAgentData(user.id, (data) => {
-          const tokens = data.appTokens ?? []
-          full = false
-          if (tokens.length >= MAX_APP_TOKENS) {
-            full = true
-            return
-          }
-          data.appTokens = [...tokens, record]
-        })
-        if (full) throw new AgentError("rate_limited", `At most ${MAX_APP_TOKENS} app tokens per user`, { hint: "Revoke unused tokens" })
-        await store.audit({ actor: user.id, action: "app-token.create", target: id, ...(input.label ? { detail: input.label } : {}) })
+        const { record, token } = await issueAppToken(store, user.id, parseCreate(await request.json()))
         return Response.json({ ...view(record), token }, { status: 201, headers: NO_STORE })
       },
     },

package/src/central/agent/archive-inactive.ts

@@ -0,0 +1,66 @@
+import { createHmac, timingSafeEqual } from "node:crypto"
+import type { DirectoryEntry } from "./directory"
+import { AgentError } from "./errors"
+
+const PREFIX = "hai1_"
+const DOMAIN = "hub-archive-inactive/v1"
+const TTL_MS = 5 * 60_000
+const invalid = () => new AgentError("invalid", "This inactive-archive preview is invalid or expired; preview again")
+
+interface Payload { readonly userID: string; readonly at: number; readonly inactiveForMs: number; readonly candidates: readonly string[] }
+export interface ArchiveSets { readonly pinned: ReadonlySet<string>; readonly archived: ReadonlySet<string> }
+export type SkipReason = "active" | "pinned" | "open" | "archived" | "not_found"
+
+export class ArchiveInactive {
+  constructor(private readonly options: { readonly secret: Buffer; readonly now?: () => number }) {}
+  private now() { return (this.options.now ?? Date.now)() }
+
+  preview(userID: string, sessions: readonly DirectoryEntry[], options: ArchiveSets & { readonly inactiveForMs: number; readonly limit: number }) {
+    const candidates = sessions
+      .filter((s) => !s.online && typeof s.lastSeen === "number" && this.now() - s.lastSeen >= options.inactiveForMs && !options.pinned.has(s.sessionID) && !options.archived.has(s.sessionID))
+      .map((s) => s.sessionID).slice(0, options.limit)
+    const payload: Payload = { userID, at: this.now(), inactiveForMs: options.inactiveForMs, candidates }
+    return { candidates, previewToken: this.encode(payload), expiresAt: payload.at + TTL_MS }
+  }
+
+  decode(userID: string, token: string): Payload {
+    if (!token.startsWith(PREFIX) || token.length > 10_000) throw invalid()
+    const [body, tag, ...rest] = token.slice(PREFIX.length).split(".")
+    if (rest.length || !body || !tag) throw invalid()
+    const expected = createHmac("sha256", this.options.secret).update(`${DOMAIN}\n${body}`).digest().subarray(0, 16)
+    const given = Buffer.from(tag, "base64url")
+    if (given.length !== expected.length || !timingSafeEqual(given, expected)) throw invalid()
+    let payload: Payload
+    try { payload = JSON.parse(Buffer.from(body, "base64url").toString("utf8")) as Payload } catch { throw invalid() }
+    if (payload.userID !== userID || !Array.isArray(payload.candidates) || this.now() - payload.at > TTL_MS) throw invalid()
+    return payload
+  }
+
+  revalidate(userID: string, token: string, sessions: readonly DirectoryEntry[], options: ArchiveSets & { readonly open: ReadonlySet<string>; readonly active: ReadonlySet<string> }) {
+    const payload = this.decode(userID, token)
+    const byID = new Map(sessions.map((s) => [s.sessionID, s]))
+    const candidates: string[] = []
+    const skipped: Array<{ sessionID: string; reason: SkipReason }> = []
+    for (const sessionID of payload.candidates) {
+      const s = byID.get(sessionID)
+      const reason: SkipReason | undefined = !s ? "not_found" : options.archived.has(sessionID) ? "archived" : options.pinned.has(sessionID) ? "pinned" : options.open.has(sessionID) ? "open" : options.active.has(sessionID) || s.online ? "active" : undefined
+      if (reason) skipped.push({ sessionID, reason }); else candidates.push(sessionID)
+    }
+    return { candidates, skipped }
+  }
+
+  private encode(payload: Payload) {
+    const body = Buffer.from(JSON.stringify(payload)).toString("base64url")
+    const tag = createHmac("sha256", this.options.secret).update(`${DOMAIN}\n${body}`).digest().subarray(0, 16).toString("base64url")
+    return `${PREFIX}${body}.${tag}`
+  }
+}
+
+export function parseInactiveFor(value: unknown): number {
+  if (typeof value !== "string") throw new AgentError("invalid", "inactiveFor must be a duration such as 7d")
+  const m = /^(\d+)(h|d)$/.exec(value)
+  if (!m) throw new AgentError("invalid", "inactiveFor must be a duration such as 7d")
+  const ms = Number(m[1]) * (m[2] === "d" ? 86_400_000 : 3_600_000)
+  if (ms < 3_600_000 || ms > 365 * 86_400_000) throw new AgentError("invalid", "inactiveFor must be from 1h to 365d")
+  return ms
+}