@huynle/hub 0.7.4 → 0.8.1

package/packages/sdk/src/types.ts

@@ -50,6 +50,33 @@ export interface SessionView {
   /** In sessions answers. */
   readonly machineID?: string
   readonly project?: string
+  /** (CON-02) The stored intent, when there is one (untrusted text). */
+  readonly intent?: IntentField
+}
+
+/** (CON-02) Who set a session's intent, highest precedence first. */
+export type IntentSource = "user" | "launch" | "self" | "prompt" | "title"
+
+/**
+ * (CON-02) What a session is for (GET/PUT /api/agent/sessions/:addr/intent): untrusted text, sanitised, one line,
+ * 1–280 characters. Mirrors packages/protocol SessionIntent.
+ */
+export interface SessionIntent {
+  readonly sessionID: string
+  readonly text: string
+  readonly source: IntentSource
+  /** 0 before the hub stored anything (a title fallback). */
+  readonly revision: number
+  readonly updatedAt: number
+  /** user, app:<tokenID> or ses_… */
+  readonly by?: string
+}
+
+/** (CON-02) The intent as list and show entries embed it. */
+export interface IntentField {
+  readonly text: string
+  readonly source: IntentSource
+  readonly revision: number
 }
 
 export interface AttentionItem {
@@ -71,6 +98,8 @@ export interface Status {
   }[]
   readonly attention: readonly AttentionItem[]
   readonly you?: Actor
+  /** HWA-40: the listed sessions' teams (a team member: its own teams only). */
+  readonly teams?: readonly TeamGroupView[]
 }
 
 /** GET /api/agent/sessions/:addr: one session in detail. */
@@ -86,6 +115,8 @@ export interface SessionDetail extends SessionView {
   }
   readonly unsupported?: readonly { readonly feature?: string; readonly harness?: string }[]
   readonly failed?: readonly { readonly feature?: string }[]
+  /** HWA-40: the session's teams as the caller may see them. */
+  readonly teams?: readonly TeamMembershipView[]
 }
 
 /** One timeline row (newest first). */
@@ -119,6 +150,46 @@ export interface DirectoryEntry {
   readonly lastSeen?: number
   readonly archived?: boolean
   readonly roles: readonly RoleView[]
+  /** (CON-02) The stored intent, when there is one (untrusted text). */
+  readonly intent?: IntentField
+  /** HWA-40 (additive): the harness when reported, team seats and the caller's reach (team members only). */
+  readonly harness?: string
+  readonly teams?: readonly TeamMembershipView[]
+  readonly reach?: TeamReach
+}
+
+/** HWA-40: what the caller may send to / receive from a session under team policy (from the hub's verdict). */
+export interface TeamReach {
+  readonly send: readonly ("msg" | "ask")[]
+  readonly receive: readonly ("msg" | "ask")[]
+  readonly direction: "two-way" | "outbound" | "inbound" | "none"
+  readonly unreachable?: true
+}
+
+/** HWA-40: one team a session is seated in, with its roles there. */
+export interface TeamMembershipView {
+  readonly teamID: string
+  readonly team: string
+  readonly roles: readonly string[]
+  readonly reach?: TeamReach
+}
+
+/** HWA-40: a team in who/status answers, with its listed members. */
+export interface TeamGroupView {
+  readonly teamID: string
+  readonly name: string
+  readonly title: string
+  readonly mode: "open" | "restricted"
+  readonly paused?: true
+  readonly yourRoles?: readonly string[]
+  readonly members: readonly { readonly sessionID: string; readonly role: string; readonly generation: number }[]
+}
+
+/** GET /api/agent/who. `scope: "team"`: the caller sees its teams only (HWA-40). */
+export interface WhoAnswer {
+  readonly sessions: DirectoryEntry[]
+  readonly teams?: readonly TeamGroupView[]
+  readonly scope?: "team"
 }
 
 /** One compact event of GET /api/agent/events (no free text). Unknown types are valid: ignore them. */
@@ -198,7 +269,11 @@ export type MessageKind = "msg" | "ask" | "reply" | "decline"
 /** `sent` for msg/reply/decline; asks are open until answered, declined or expired. */
 export type MessageState = "sent" | "open" | "answered" | "declined" | "expired"
 /** How a message reached its recipient session. */
-export type MessageDelivery = "steer" | "turn" | "queued" | "retained" | "pending"
+/**
+ * (CON-10) "dropped": it was pending for a session that ended for good (a retired Concierge session); never delivered.
+ * "expired": it was pending for 24 h (its recipient stayed offline or busy); never delivered, and its sender was told.
+ */
+export type MessageDelivery = "steer" | "turn" | "queued" | "retained" | "pending" | "dropped" | "expired"
 
 /** A stored agent message. */
 export interface AgentMessage {
@@ -224,10 +299,21 @@ export interface AgentMessage {
   readonly answer?: { readonly id: string; readonly at: number }
 }
 
+/**
+ * Why a message to a session did not start a turn: the sender asked wake:false, the recipient is a subagent
+ * (never woken), the reply chain went past the hop cap (8 hops without a human turn), or the recipient's wake
+ * budget (30 per 10 minutes) is spent. The message is still delivered.
+ */
+export type WakeSkip = "wake_false" | "subagent" | "hop_cap" | "budget"
+
 /** POST /api/agent/msg and /ask: the stored message and how it was delivered (none: stored only). */
 export interface Sent {
   readonly message: AgentMessage
   readonly delivery?: MessageDelivery
+  /** Messages to a session: whether the hub sent it to wake the recipient (absent from hubs before 0.8.1). */
+  readonly woke?: boolean
+  /** When woke is false: why. */
+  readonly wakeSkipped?: WakeSkip
 }
 
 /** POST /api/agent/msg or /ask with all: one per session. */
@@ -449,9 +535,13 @@ export interface LaunchSpec {
   readonly runtime?: { readonly kind: RuntimeKind; readonly profile?: string }
   readonly placement?: { readonly labels?: Readonly<Record<string, string>>; readonly machine?: string; readonly mode?: PlacementMode }
   readonly prompt?: string
+  /** (CON-02) What the session is for: one line, at most 280 characters; becomes its intent (source launch). */
+  readonly intent?: string
   /** Free-form; never interpreted by the hub (find launches and sessions by them). */
   readonly labels?: Readonly<Record<string, string>>
   readonly end?: { readonly when?: LaunchEndWhen; readonly timeout?: string; readonly cleanup?: CleanupPolicy }
+  /** Pin and apply this profile version before the prompt (explicit version; apps need profiles:assign). */
+  readonly agentProfile?: { readonly profileID: string; readonly version: number }
 }
 
 export interface LaunchStep {
@@ -501,6 +591,12 @@ export interface LaunchView {
   readonly updated: number
   /** Who launched it: `user`, `app:<token id>` or a session ID. */
   readonly by?: string
+  /** The launcher's label when it launched (an app token's label). */
+  readonly byLabel?: string
+  /** The app token that launched it was revoked: it still runs and counts toward the cap until stopped. */
+  readonly launcherRevoked?: boolean
+  /** Only while queued: why it waits (`reason` is the same text). */
+  readonly waiting?: { readonly wait: "capacity" | "no_match" | "active"; readonly reason: string; readonly since: number }
   readonly machineID?: string
   readonly directory?: string
   readonly sessionID?: string
@@ -515,3 +611,474 @@ export interface LaunchCreated {
   readonly launch: LaunchView
   readonly created: boolean
 }
+
+// Profiles (HWA-14; packages/protocol/src/profiles.ts is the wire source of truth). A profile is a versioned bundle
+// of instructions, skills and commands; versions are immutable, and a session pins one. Assigning confers no
+// authority.
+
+export type ProfileState = "active" | "archived"
+
+export interface ProfileSkill {
+  readonly name: string
+  readonly description: string
+  readonly body: string
+}
+
+export interface ProfileCommand {
+  readonly name: string
+  readonly description: string
+  /** Text with {{name}} parameters and {{secret:NAME}} references (never resolved by the hub). */
+  readonly template: string
+}
+
+export interface ProfileContent {
+  readonly instructions?: string
+  readonly model?: string
+  readonly skills: readonly ProfileSkill[]
+  readonly commands: readonly ProfileCommand[]
+}
+
+export interface ProfileView {
+  readonly v: 1
+  readonly id: string
+  readonly name: string
+  readonly title: string
+  readonly description?: string
+  readonly state: ProfileState
+  readonly tags?: readonly string[]
+  /** (RP-08) Optional bounded key/value details (≤ 32 slug keys, values 1–200 characters). */
+  readonly metadata?: Readonly<Record<string, string>>
+  /** (RP-08) Project names the profile is meant for (≤ 16). */
+  readonly projects?: readonly string[]
+  readonly latestVersion: number
+  readonly revision: number
+  readonly updatedAt: number
+}
+
+export interface ProfileVersion {
+  readonly v: 1
+  readonly profileID: string
+  readonly version: number
+  readonly content: ProfileContent
+  readonly digest: string
+  readonly createdAt: number
+}
+
+/** A version without its bodies (load skills on demand). */
+export interface ProfileVersionSummary {
+  readonly profileID: string
+  readonly version: number
+  readonly digest: string
+  readonly createdAt: number
+  readonly bytes: number
+  readonly instructions: boolean
+  readonly model?: string
+  readonly skills: readonly { readonly name: string; readonly description: string }[]
+  readonly commands: readonly { readonly name: string; readonly description: string; readonly params: readonly string[] }[]
+  readonly secretRefs: readonly string[]
+}
+
+export interface ProfileVersionEntry {
+  readonly version: number
+  readonly digest: string
+  readonly bytes: number
+  readonly createdAt: number
+  /** (RP-08) Content counts (absent on versions written before). */
+  readonly skills?: number
+  readonly commands?: number
+  readonly instructions?: boolean
+}
+
+export interface ProfileCreated {
+  readonly profile: ProfileView
+  readonly version: ProfileVersionSummary
+  /** Import only: what was dropped or defaulted. */
+  readonly notes?: readonly string[]
+}
+
+export interface ProfileAck {
+  /** restart_required: accepted, effective after the session restarts. */
+  readonly status: "pending" | "applied" | "partial" | "rejected" | "unsupported" | "restart_required"
+  readonly digest: string
+  readonly notes?: readonly string[]
+  readonly at: number
+  /** With pending: no spoke reports the session now; applied when one does. */
+  readonly offline?: true
+}
+
+/** The version a session last confirmed running (kept across later pins). */
+export interface ProfileEffective {
+  readonly profileID: string
+  readonly version: number
+  readonly digest: string
+  readonly status: "applied" | "partial"
+  readonly at: number
+}
+
+export interface ProfileAssignment {
+  readonly v: 1
+  readonly sessionID: string
+  readonly profileID: string
+  readonly version: number
+  readonly revision: number
+  readonly ack?: ProfileAck
+  readonly effective?: ProfileEffective
+}
+
+export interface SessionProfile {
+  readonly assignment: ProfileAssignment | null
+  readonly profile?: ProfileView
+  readonly version?: ProfileVersionSummary
+}
+
+export interface ProfileSkillLoaded {
+  readonly skill: ProfileSkill
+  readonly profileID: string
+  readonly version: number
+}
+
+export interface ProfileRendered {
+  /** The rendered text; sending it to a session is a separate prompt (its own grants). */
+  readonly prompt: string
+  readonly secretRefs: readonly string[]
+  readonly profileID: string
+  readonly version: number
+  readonly command: string
+}
+
+export interface ProfilePage<T> {
+  readonly items: readonly T[]
+  readonly cursor?: string
+}
+
+// Profile usage (RP-08): GET /profiles/:id/usage and GET /profiles?include=usage. A category the caller may not read
+// (app scopes: sessions:read, teams:read|teams:manage, sessions:launch, workspaces:read + sessions:read) is left out
+// and named in `hidden`; lists past their cap are named in `truncated` (counts stay exact).
+export type ProfileUsageCategory = "sessions" | "teams" | "launches" | "workspaces"
+
+export interface ProfileUsageCounts {
+  readonly sessions?: number
+  readonly online?: number
+  /** Sessions pinned to a version older than the latest. */
+  readonly olderVersion?: number
+  readonly teamRoles?: number
+  /** Seat occupancy: only for callers who may also read sessions (apps: sessions:read). */
+  readonly staffedSeats?: number
+  readonly launches?: number
+  readonly liveLaunches?: number
+  readonly workspaces?: number
+}
+
+export interface ProfileUsageListCounts extends ProfileUsageCounts {
+  /** Team names (slugs) whose roles name the profile. */
+  readonly teams?: readonly string[]
+  readonly harnesses?: readonly string[]
+}
+
+export interface ProfileUsageSession {
+  readonly sessionID: string
+  readonly name?: string
+  readonly title?: string
+  readonly machineID?: string
+  readonly harness?: string
+  readonly project?: string
+  readonly online: boolean
+  readonly lastSeen?: number
+  /** false: no longer in the directory (the pin is still stored). */
+  readonly known?: false
+  /** The requested (pinned) version and the pin's revision (expectedRevision for an explicit upgrade). */
+  readonly version: number
+  readonly revision: number
+  readonly olderVersion: boolean
+  readonly ack?: { readonly status: ProfileAck["status"]; readonly at: number; readonly offline?: true }
+  readonly effective?: { readonly version: number; readonly status: "applied" | "partial"; readonly at: number }
+}
+
+export interface ProfileUsage {
+  readonly profileID: string
+  readonly latestVersion: number
+  readonly counts: ProfileUsageCounts
+  readonly sessions?: ProfilePage<ProfileUsageSession>
+  readonly projects?: readonly string[]
+  readonly teamRoles?: readonly { readonly teamID: string; readonly teamName: string; readonly teamTitle: string; readonly role: string; readonly label?: string; readonly version?: number; /** Only with sessions:read (users always). */ readonly staffed?: number }[]
+  readonly launches?: readonly { readonly id: string; readonly state: string; readonly outcome?: string; readonly version: number; readonly sessionID?: string; readonly created: number; readonly updated: number }[]
+  readonly workspaces?: readonly { readonly workspaceID: string; readonly title?: string; readonly sessions: number }[]
+  readonly hidden?: readonly ProfileUsageCategory[]
+  readonly truncated?: readonly ("sessions" | "teamRoles" | "launches" | "workspaces")[]
+}
+
+export type ProfileListInclude = "usage" | "summary"
+
+/** GET /profiles?include=usage,summary: the page plus counts per listed profile. */
+export interface ProfileListPage extends ProfilePage<ProfileView> {
+  readonly usage?: Readonly<Record<string, ProfileUsageListCounts>>
+  /** include=summary: the latest version's counts. */
+  readonly summaries?: Readonly<Record<string, { readonly version: number; readonly skills: number; readonly commands: number; readonly instructions: boolean }>>
+  readonly hidden?: readonly ProfileUsageCategory[]
+  readonly truncated?: readonly "sessions"[]
+}
+
+// Workspaces (HWA-06; packages/protocol/src/hub-workspace.ts is the wire source of truth). A workspace is a durable,
+// owner-tenanted coordination record: host repo bindings, members (sessions by ID), assignments and a supervision
+// graph. Membership, roles and supervision confer no authority; native parent/root session ancestry is untouched.
+
+export type WorkspaceState = "active" | "archived"
+export type WorkspaceRole = "master" | "worker" | "observer"
+export type WorkspaceAssignmentStatus = "open" | "in_progress" | "blocked" | "done" | "cancelled"
+/** What the hub knows about a member's session now. */
+export type WorkspaceSessionPresence = "online" | "offline" | "archived" | "deleted" | "unknown"
+
+export interface WorkspaceView {
+  readonly v: 1
+  readonly id: string
+  readonly title: string
+  readonly description?: string
+  readonly state: WorkspaceState
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly masterMemberID?: string
+  readonly revision: number
+  readonly createdAt: number
+  readonly updatedAt: number
+}
+
+export interface WorkspaceBinding {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly machineID: string
+  readonly repo: string
+  readonly label?: string
+  readonly revision: number
+}
+
+export interface WorkspaceMemberRecord {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly sessionID: string
+  readonly role: WorkspaceRole
+  readonly generation: number
+  readonly joinedAt: number
+  readonly leftAt?: number
+  readonly leftReason?: "removed" | "replaced" | "ended" | "archived"
+  readonly revision: number
+}
+
+export interface WorkspaceMemberView {
+  readonly member: WorkspaceMemberRecord
+  readonly current: boolean
+  readonly presence: WorkspaceSessionPresence
+}
+
+export interface WorkspaceAssignmentRecord {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly memberID: string
+  readonly title: string
+  readonly status: WorkspaceAssignmentStatus
+  readonly ref?: string
+  readonly criteria?: readonly string[]
+  readonly revision: number
+  readonly createdAt: number
+  readonly updatedAt: number
+  readonly closedAt?: number
+}
+
+export interface WorkspaceAssignmentView {
+  readonly assignment: WorkspaceAssignmentRecord
+  readonly member: "current" | "left" | "missing"
+  readonly presence: WorkspaceSessionPresence
+}
+
+export interface WorkspaceSupervisionLink {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly supervisorMemberID: string
+  readonly memberID: string
+  readonly order: number
+  readonly revision: number
+}
+
+export interface WorkspaceSupervisionGraph {
+  readonly workspaceID: string
+  /** The graph revision a supervise call names as expectedRevision (0: never written). */
+  readonly revision: number
+  readonly links: readonly { readonly link: WorkspaceSupervisionLink; readonly member: "current" | "left" | "missing"; readonly supervisor: "current" | "left" | "missing" }[]
+}
+
+export interface WorkspaceSupervised {
+  readonly workspaceID: string
+  readonly revision: number
+  readonly change: "attached" | "moved" | "reordered" | "detached" | "unchanged"
+  readonly link?: WorkspaceSupervisionLink
+  readonly pruned: number
+}
+
+export interface WorkspaceDeparture {
+  readonly member: WorkspaceMemberRecord
+  readonly supervision: { readonly workspaceID: string; readonly revision: number; readonly detached: number; readonly transferred: number; readonly pruned: number }
+}
+
+/** GET /workspaces/:id/master (HWA-12): the current master, earlier masters (newest first) and a replacement in flight. */
+export interface WorkspaceMasterView {
+  readonly workspaceID: string
+  readonly revision: number
+  readonly master?: { readonly member: WorkspaceMemberRecord; readonly presence: WorkspaceSessionPresence }
+  readonly previous: readonly { readonly member: WorkspaceMemberRecord; readonly presence: WorkspaceSessionPresence }[]
+  readonly pending?: { readonly phase: "claimed" | "joined"; readonly at: number; readonly stale: boolean }
+}
+
+/** POST /workspaces/:id/master (HWA-12). No grants move; the new master starts from a fresh digest snapshot. */
+export interface WorkspaceMasterReplaced {
+  readonly workspace: WorkspaceView
+  readonly master: WorkspaceMemberRecord
+  readonly presence: WorkspaceSessionPresence
+  readonly previous?: WorkspaceMemberRecord
+  readonly previousPresence?: WorkspaceSessionPresence
+  /** False when the session already was the master. */
+  readonly changed: boolean
+  readonly supervision?: { readonly workspaceID: string; readonly revision: number; readonly detached: number; readonly transferred: number; readonly pruned: number }
+  readonly checkpoints: { readonly inherited: false; readonly previousCheckpoint?: { readonly id: string; readonly supervisorMemberID: string; readonly cursor: string; readonly at: number; readonly generation: number; readonly sessionID: string } }
+  readonly grants: { readonly transferred: false; readonly note: string }
+}
+
+export interface WorkspaceArchived {
+  readonly workspace: WorkspaceView
+  readonly departed: number
+  readonly supervision: { readonly detached: number }
+}
+
+export interface WorkspacePage<T> {
+  readonly items: readonly T[]
+  readonly cursor?: string
+}
+
+/** One section of the board an app may lack the scope for, that this hub doesn't serve, or whose source failed. */
+export type WorkspaceBoardSection<T> =
+  | { readonly status: "ok"; readonly items: readonly T[]; readonly truncated: boolean }
+  | { readonly status: "omitted"; readonly reason: "scope"; readonly scope: string }
+  | { readonly status: "unsupported"; readonly feature: string }
+  | { readonly status: "failed" }
+
+/**
+ * GET /workspaces/:id/board (HWA-10): a read-only, bounded situation snapshot. References and states only; detail
+ * text (prompts, Decision questions, blocker summaries, criteria, artifact content) stays behind its own routes.
+ */
+export interface WorkspaceBoard {
+  readonly v: 1
+  readonly at: number
+  /** Open assignments without an update for this long carry `no_recent_update`. */
+  readonly staleAfterMs: number
+  readonly workspace: { readonly id: string; readonly title: string; readonly state: WorkspaceState; readonly revision: number; readonly masterMemberID?: string; readonly createdAt: number; readonly updatedAt: number }
+  readonly members: {
+    readonly items: readonly {
+      readonly memberID: string
+      readonly sessionID: string
+      readonly role: WorkspaceRole
+      readonly generation: number
+      readonly revision: number
+      readonly joinedAt: number
+      readonly master: boolean
+      readonly presence: WorkspaceSessionPresence
+      /** Absent when the hub doesn't know the session now. */
+      readonly session?: { readonly state: string; readonly online: boolean; readonly lastSeen?: number; readonly machineID?: string; readonly name?: string; readonly busySince?: number }
+      /** `reported: false`: this hub's catalog doesn't report the session now (not "no blockers"). */
+      readonly blockers: { readonly reported: false } | { readonly reported: true; readonly count: number; readonly items: readonly { readonly kind: string; readonly id: string; readonly sessionID?: string }[]; readonly truncated?: true }
+      readonly assignments: { readonly open: number; readonly in_progress: number; readonly blocked: number }
+      readonly decisions?: number
+      readonly stale?: Exclude<WorkspaceSessionPresence, "online">
+    }[]
+    readonly total: number
+    readonly truncated: boolean
+  }
+  readonly supervision: { readonly revision: number; readonly links: readonly { readonly memberID: string; readonly supervisorMemberID: string; readonly order: number; readonly member: "current" | "left" | "missing"; readonly supervisor: "current" | "left" | "missing" }[]; readonly truncated: boolean }
+  readonly assignments: {
+    readonly items: readonly {
+      readonly id: string
+      readonly memberID: string
+      readonly title: string
+      /** Exactly the stored status: never inferred from idleness or presence. */
+      readonly status: WorkspaceAssignmentStatus
+      readonly ref?: string
+      readonly revision: number
+      readonly createdAt: number
+      readonly updatedAt: number
+      readonly closedAt?: number
+      readonly assignee: "current" | "left" | "missing"
+      readonly stale?: readonly ("assignee_left" | "assignee_missing" | "assignee_offline" | "no_recent_update")[]
+    }[]
+    readonly counts: Readonly<Record<WorkspaceAssignmentStatus, number>>
+    readonly truncated: boolean
+  }
+  readonly decisions: WorkspaceBoardSection<{ readonly id: string; readonly state: string; readonly urgency: string; readonly tier: string; readonly at: number; readonly expiresAt: number; readonly deadline?: number; readonly escalatedAt?: number; readonly sessionIDs: readonly string[]; readonly memberIDs: readonly string[]; readonly stale?: "past_deadline" }>
+  readonly artifacts: WorkspaceBoardSection<{ readonly id: string; readonly kind: string; readonly visibility: string; readonly state: string; readonly revision: number; readonly latestRevisionID: string; readonly updatedAt: number }>
+}
+
+/** One quoted source message of a side chat's context snapshot (HWA-13). */
+export interface WorkspaceSideChatItem {
+  readonly kind: "message"
+  readonly id: string
+  readonly role: "user" | "assistant" | "message"
+  readonly at?: number
+  readonly pos?: number
+  readonly text: string
+  readonly bytes: number
+  readonly clipped?: true
+  /** Refresh markers: changed since the previous snapshot, or no longer readable (the previous copy is kept). */
+  readonly changed?: true
+  readonly stale?: "missing"
+}
+
+/** A side chat's bounded context snapshot: exactly what the side-chat session was given. */
+export interface WorkspaceSideChatSnapshot {
+  readonly generation: number
+  readonly takenAt: number
+  readonly mode: "selected" | "recent"
+  readonly items: readonly WorkspaceSideChatItem[]
+  readonly bytes: number
+  readonly omitted: number
+  readonly sourceNewestAt?: number
+}
+
+interface WorkspaceSideChatBase {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  /** The side-chat session, once its launch reports it. */
+  readonly sessionID?: string
+  readonly sourceSessionID: string
+  readonly sources: readonly { readonly kind: "message" | "artifact_revision"; readonly id: string }[]
+  readonly launchID: string
+  readonly by: string
+  readonly bindingID: string
+  readonly machineID: string
+  readonly harness: string
+  readonly revision: number
+  readonly createdAt: number
+  readonly updatedAt: number
+  /** ready: the side-chat session exists; launching: its launch is under way (or waiting for the machine). */
+  readonly status: "launching" | "ready" | "failed" | "unknown"
+  readonly launch?: { readonly id: string; readonly state: string; readonly outcome?: string; readonly reason?: string }
+  /** When the hub knows the source's last change: newer than the snapshot = stale. */
+  readonly sourceUpdatedAt?: number
+  readonly stale?: boolean
+}
+
+/** A side chat with its snapshot (create, get, refresh). */
+export interface WorkspaceSideChat extends WorkspaceSideChatBase {
+  readonly snapshot: WorkspaceSideChatSnapshot
+}
+
+/** A side chat in a list: the snapshot's summary, without quoted text. */
+export interface WorkspaceSideChatSummary extends WorkspaceSideChatBase {
+  readonly snapshot: Omit<WorkspaceSideChatSnapshot, "items"> & { readonly count: number }
+}
+
+/** How a refreshed context reached the side-chat session (a queued message). */
+export type WorkspaceSideChatDelivery =
+  | { readonly status: "not_started" }
+  | { readonly status: "sent"; readonly message: unknown; readonly delivery?: string }
+  | { readonly status: "failed"; readonly code: string; readonly message: string }

package/packages/sdk/src/wake.ts

@@ -0,0 +1,20 @@
+// Why a message did not wake its recipient (Sent.woke / Sent.wakeSkipped, hub 0.8.1), in the words the CLI, `hub mcp`
+// and the OpenCode hub tool show: one place so every client says the same thing.
+import type { Sent, WakeSkip } from "./types.ts"
+
+/** One short reason per WakeSkip. */
+export const WAKE_SKIP_TEXT: Readonly<Record<WakeSkip, string>> = {
+  wake_false: "sent without a wake",
+  subagent: "subagents are never woken",
+  hop_cap: "hop limit reached (8 agent messages without a human turn)",
+  budget: "wake budget spent (30 per 10 minutes)",
+}
+
+/**
+ * ` — wake skipped: <reason>` when the hub did not wake the recipient and the message waits for a later turn; empty
+ * when it woke, went into a running turn (steer) or started one, or the hub did not say (hubs before 0.8.1).
+ */
+export function wakeSkipNote({ delivery, woke, wakeSkipped }: Pick<Sent, "delivery" | "woke" | "wakeSkipped">): string {
+  if (woke !== false || !wakeSkipped || delivery === "steer" || delivery === "turn") return ""
+  return ` — wake skipped: ${WAKE_SKIP_TEXT[wakeSkipped] ?? wakeSkipped}`
+}

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "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/index.ts

@@ -10,3 +10,4 @@ export * from "./session-tokens.ts"
 export * from "./session-ids.ts"
 export * from "./harness-hello.ts"
 export * from "./harness-spoke.ts"
+export * from "./profile-apply.ts"