@huynle/hub 0.7.3 → 0.8.0

package/packages/sdk/src/client.ts

@@ -2,6 +2,9 @@
 // HubError (the envelope) or HubTransportError (errors.ts). Typed verbs are added on top of call()/request().
 import { envelopeOf, HubError, HubTransportError } from "./errors.ts"
 import { sseEvents } from "./sse.ts"
+import { type Artifacts, artifactsApi } from "./artifacts.ts"
+import { type Teams, teamsApi } from "./teams.ts"
+import { type Concierge, conciergeApi } from "./concierge.ts"
 import type {
   Approved,
   AppTokenView,
@@ -18,6 +21,7 @@ import type {
   DecisionUrgency,
   Denied,
   DirectoryEntry,
+  WhoAnswer,
   FormAnswer,
   FormAnswered,
   Grant,
@@ -34,6 +38,7 @@ import type {
   PromptDelivery,
   Prompted,
   Pinned,
+  SessionIntent,
   Replied,
   RoleClaim,
   RoleRelease,
@@ -48,6 +53,41 @@ import type {
   Whoami,
   WebhookDelivery,
   WebhookView,
+  ProfileAssignment,
+  ProfileContent,
+  ProfileCreated,
+  ProfileListInclude,
+  ProfileListPage,
+  ProfilePage,
+  ProfileUsage,
+  ProfileRendered,
+  ProfileSkillLoaded,
+  ProfileState,
+  ProfileVersion,
+  ProfileVersionEntry,
+  ProfileVersionSummary,
+  ProfileView,
+  SessionProfile,
+  WorkspaceArchived,
+  WorkspaceAssignmentRecord,
+  WorkspaceAssignmentStatus,
+  WorkspaceAssignmentView,
+  WorkspaceBinding,
+  WorkspaceBoard,
+  WorkspaceDeparture,
+  WorkspaceMasterReplaced,
+  WorkspaceMasterView,
+  WorkspaceMemberRecord,
+  WorkspaceMemberView,
+  WorkspacePage,
+  WorkspaceRole,
+  WorkspaceSideChat,
+  WorkspaceSideChatDelivery,
+  WorkspaceSideChatSummary,
+  WorkspaceState,
+  WorkspaceSupervised,
+  WorkspaceSupervisionGraph,
+  WorkspaceView,
 } from "./types.ts"
 
 const AGENT = "/api/agent"
@@ -62,7 +102,11 @@ export interface RequestOptions {
   readonly query?: Readonly<Record<string, QueryValue>>
   /** Sent as JSON. */
   readonly body?: unknown
+  /** Sent as is with its own content type, instead of a JSON body (artifact blob uploads). */
+  readonly raw?: { readonly body: BodyInit; readonly contentType: string }
   readonly signal?: AbortSignal
+  /** Extra request headers (e.g. Idempotency-Key); authorization and content headers are the client's. */
+  readonly headers?: Readonly<Record<string, string>>
 }
 
 /** The part of fetch the client uses. */
@@ -106,6 +150,8 @@ export interface SessionsFilter extends CallOptions {
   readonly machine?: string
   /** `key=value` labels, all of which must match. */
   readonly label?: readonly string[]
+  /** (CON-11) Words that must all appear in the title or @name (case and punctuation ignored; ≤ 200 characters). */
+  readonly q?: string
 }
 
 export interface LaunchesFilter extends CallOptions {
@@ -126,6 +172,105 @@ export interface Launches {
   stop(id: string, options?: CallOptions): Promise<{ launch: LaunchView }>
 }
 
+export interface IdempotentOptions extends CallOptions {
+  /** The same key and body within 24 h answer the first result again (Idempotency-Key). */
+  readonly idempotencyKey?: string
+}
+
+export interface ProfilesFilter extends CallOptions {
+  readonly state?: ProfileState | "all"
+  readonly limit?: number
+  readonly cursor?: string
+  /** (RP-08) "usage": per-profile usage counts (ProfileListPage.usage); "summary": latest version counts (summaries). */
+  readonly include?: ProfileListInclude | readonly ProfileListInclude[]
+}
+
+/**
+ * hub.profiles (HWA-14): versioned agent profiles (instructions, skills, commands). Users; app tokens with
+ * profiles:read / profiles:manage / profiles:assign (session routes also need sessions:read); session tokens read
+ * only their own pinned profile (ofSession, sessionSkill, sessionRender). Mutations take expectedRevision; a stale
+ * one is HubError conflict with envelope.currentRevision.
+ */
+export interface Profiles {
+  create(input: { readonly name: string; readonly title: string; readonly description?: string; readonly tags?: readonly string[]; readonly metadata?: Readonly<Record<string, string>>; readonly projects?: readonly string[]; readonly content: ProfileContent }, options?: IdempotentOptions): Promise<ProfileCreated>
+  /** From AGENTS.md / skills/<name>/SKILL.md / commands/<name>.md text files; anything else is unsupported. */
+  import(input: { readonly name: string; readonly title: string; readonly description?: string; readonly tags?: readonly string[]; readonly files: readonly { readonly path: string; readonly text: string }[] }, options?: IdempotentOptions): Promise<ProfileCreated>
+  list(filter?: ProfilesFilter): Promise<ProfileListPage>
+  get(id: string, options?: CallOptions): Promise<{ profile: ProfileView; latest?: ProfileVersionSummary }>
+  /** metadata/projects replace the stored ones; null clears them (RP-08). */
+  update(
+    id: string,
+    patch: { readonly expectedRevision: number; readonly title?: string; readonly description?: string | null; readonly tags?: readonly string[]; readonly state?: ProfileState; readonly metadata?: Readonly<Record<string, string>> | null; readonly projects?: readonly string[] | null },
+    options?: CallOptions,
+  ): Promise<{ profile: ProfileView }>
+  /** (RP-08) Where the profile is used: pinned sessions (paged), team roles, launches, workspaces; per-category scopes. */
+  usage(id: string, options?: CallOptions & { readonly limit?: number; readonly cursor?: string }): Promise<ProfileUsage>
+  versions(id: string, options?: CallOptions & { readonly limit?: number; readonly cursor?: string }): Promise<ProfilePage<ProfileVersionEntry>>
+  /** A new immutable version from content, an older version (explicit rollback) or files. */
+  createVersion(id: string, input: { readonly expectedRevision: number } & ({ readonly content: ProfileContent } | { readonly fromVersion: number } | { readonly files: readonly { readonly path: string; readonly text: string }[] }), options?: IdempotentOptions): Promise<ProfileCreated>
+  version(id: string, version: number, options?: CallOptions): Promise<{ version: ProfileVersion }>
+  skill(id: string, version: number, name: string, options?: CallOptions): Promise<ProfileSkillLoaded>
+  render(id: string, version: number, name: string, params: Readonly<Record<string, string>>, options?: CallOptions): Promise<ProfileRendered>
+  ofSession(addr: string, options?: CallOptions): Promise<SessionProfile>
+  assign(addr: string, input: { readonly profileID: string; readonly version: number; readonly expectedRevision: number }, options?: CallOptions): Promise<{ assignment: ProfileAssignment }>
+  unassign(addr: string, expectedRevision: number, options?: CallOptions): Promise<void>
+  sessionSkill(addr: string, name: string, options?: CallOptions): Promise<ProfileSkillLoaded>
+  sessionRender(addr: string, name: string, params: Readonly<Record<string, string>>, options?: CallOptions): Promise<ProfileRendered>
+}
+
+/**
+ * hub.workspaces (HWA-06): coordination workspaces with bindings, members, assignments and supervision. Users;
+ * app tokens with workspaces:read / workspaces:manage (member and assignment routes also need sessions:read);
+ * session tokens are refused. Every change of an existing record takes expectedRevision (supervise: the graph's
+ * revision from supervision()); a stale one is HubError conflict with envelope.currentRevision. Nothing here
+ * grants authority.
+ */
+export interface Workspaces {
+  create(input: { readonly title: string; readonly description?: string; readonly tags?: readonly string[]; readonly metadata?: Readonly<Record<string, string>> }, options?: IdempotentOptions): Promise<{ workspace: WorkspaceView }>
+  list(filter?: CallOptions & { readonly state?: WorkspaceState; readonly limit?: number; readonly cursor?: string }): Promise<WorkspacePage<WorkspaceView>>
+  get(id: string, options?: CallOptions): Promise<{ workspace: WorkspaceView; bindings: readonly WorkspaceBinding[] }>
+  update(id: string, patch: { readonly expectedRevision: number; readonly title?: string; readonly description?: string | null; readonly tags?: readonly string[] | null; readonly metadata?: Readonly<Record<string, string>> | null }, options?: CallOptions): Promise<{ workspace: WorkspaceView }>
+  /** Archives it: current members depart (`archived`) and their supervision links are detached. */
+  archive(id: string, expectedRevision: number, options?: CallOptions): Promise<WorkspaceArchived>
+  restore(id: string, expectedRevision: number, options?: CallOptions): Promise<{ workspace: WorkspaceView }>
+  bindings(id: string, options?: CallOptions): Promise<{ bindings: readonly WorkspaceBinding[] }>
+  bind(id: string, input: { readonly machineID: string; readonly repo: string; readonly label?: string }, options?: IdempotentOptions): Promise<{ binding: WorkspaceBinding; created: boolean }>
+  unbind(id: string, bindingID: string, expectedRevision: number, options?: CallOptions): Promise<void>
+  members(id: string, options?: CallOptions & { readonly includeLeft?: boolean }): Promise<{ members: readonly WorkspaceMemberView[] }>
+  join(id: string, input: { readonly sessionID: string; readonly role: Exclude<WorkspaceRole, "master"> }, options?: IdempotentOptions): Promise<{ member: WorkspaceMemberRecord; created: boolean }>
+  setRole(id: string, memberID: string, role: Exclude<WorkspaceRole, "master">, expectedRevision: number, options?: CallOptions): Promise<{ member: WorkspaceMemberRecord }>
+  /** Removes a member (`removed`) and detaches its supervision links. */
+  leave(id: string, memberID: string, expectedRevision: number, options?: CallOptions): Promise<WorkspaceDeparture>
+  assignments(id: string, filter?: CallOptions & { readonly memberID?: string; readonly status?: WorkspaceAssignmentStatus; readonly limit?: number; readonly cursor?: string }): Promise<WorkspacePage<WorkspaceAssignmentView>>
+  assignment(id: string, assignmentID: string, options?: CallOptions): Promise<{ assignment: WorkspaceAssignmentRecord }>
+  assign(id: string, input: { readonly memberID: string; readonly title: string; readonly status?: "open" | "in_progress" | "blocked"; readonly criteria?: readonly string[]; readonly ref?: string }, options?: IdempotentOptions): Promise<{ assignment: WorkspaceAssignmentRecord }>
+  setAssignmentStatus(id: string, assignmentID: string, status: WorkspaceAssignmentStatus, expectedRevision: number, options?: CallOptions): Promise<{ assignment: WorkspaceAssignmentRecord }>
+  reassign(id: string, assignmentID: string, memberID: string, expectedRevision: number, options?: CallOptions): Promise<{ assignment: WorkspaceAssignmentRecord }>
+  supervision(id: string, options?: CallOptions): Promise<WorkspaceSupervisionGraph>
+  /** Attaches, moves, reorders or (supervisorMemberID null) detaches a member's supervisor. */
+  supervise(id: string, input: { readonly memberID: string; readonly supervisorMemberID: string | null; readonly order?: number; readonly expectedRevision: number }, options?: CallOptions): Promise<WorkspaceSupervised>
+  /** The situation board (HWA-10): bounded, read-only; apps also need sessions:read. */
+  board(id: string, options?: CallOptions): Promise<WorkspaceBoard>
+  /** The current master, earlier masters and a replacement in flight (HWA-12); apps also need sessions:read. */
+  master(id: string, options?: CallOptions): Promise<WorkspaceMasterView>
+  /** Replaces (or first sets) the master under the workspace revision; sessionID or a running launch's launchID. No grants move. */
+  replaceMaster(id: string, input: ({ readonly sessionID: string } | { readonly launchID: string }) & { readonly expectedRevision: number }, options?: IdempotentOptions): Promise<WorkspaceMasterReplaced>
+  /**
+   * Side chats (HWA-13): a new session launched (through the launch API, under your launch authority) on a host
+   * binding of the workspace, started with a bounded copy of the source's messages (none named: the newest).
+   * Apps also need sessions:read, messages:read and the launch scope and grant.
+   */
+  createSideChat(id: string, input: { readonly sourceSessionID: string; readonly sources?: readonly { readonly kind: "message"; readonly id: string }[]; readonly bindingID?: string; readonly harness?: string; readonly model?: string; readonly agent?: string }, options?: IdempotentOptions): Promise<{ sideChat: WorkspaceSideChat }>
+  sideChats(id: string, filter?: CallOptions & { readonly limit?: number; readonly cursor?: string }): Promise<WorkspacePage<WorkspaceSideChatSummary>>
+  sideChat(id: string, sideChatID: string, options?: CallOptions): Promise<{ sideChat: WorkspaceSideChat }>
+  /** A side chat by its ID alone (panes know only that). */
+  sideChatByID(sideChatID: string, options?: CallOptions): Promise<{ sideChat: WorkspaceSideChat }>
+  /** Re-reads the source (ACL checked again) and sends the new context to the side-chat session as a queued message. */
+  refreshSideChat(id: string, sideChatID: string, expectedRevision: number, options?: CallOptions): Promise<{ sideChat: WorkspaceSideChat; delivery: WorkspaceSideChatDelivery }>
+  /** Users only: a confirmed, queued message to the source session (never steers its running turn). */
+  sendToMain(id: string, sideChatID: string, text: string, options?: CallOptions): Promise<{ sideChatID: string; sent: { message: unknown; delivery?: string } }>
+}
+
 export interface TargetOptions extends CallOptions {
   /** Act on this session (address) instead of the caller's own. */
   readonly session?: string
@@ -189,6 +334,7 @@ export interface PromptOptions extends ActOptions {
 const whyField = (options: ActOptions) => (options.why !== undefined ? { why: options.why } : {})
 
 const signalOf = (options: CallOptions) => (options.signal ? { signal: options.signal } : {})
+const idempotent = (options: IdempotentOptions) => ({ ...signalOf(options), ...(options.idempotencyKey ? { headers: { "idempotency-key": options.idempotencyKey } } : {}) })
 /** The wake and urgent fields of a send, when given. */
 const sendFields = (options: MsgOptions) => ({ ...(options.wake !== undefined ? { wake: options.wake } : {}), ...(options.urgent !== undefined ? { urgent: options.urgent } : {}) })
 /** The session and project fields of a role request, when given. */
@@ -216,6 +362,66 @@ export class HubClient {
     stop: (id, options = {}) => this.call("DELETE", `${AGENT}/launches/${segment(id)}`, signalOf(options)),
   }
 
+  /** Profiles (HWA-14). */
+  readonly profiles: Profiles = {
+    create: (input, options = {}) => this.call("POST", `${AGENT}/profiles`, { body: input, ...idempotent(options) }),
+    import: (input, options = {}) => this.call("POST", `${AGENT}/profiles/import`, { body: input, ...idempotent(options) }),
+    list: (filter = {}) => this.call("GET", `${AGENT}/profiles`, { query: { state: filter.state, limit: filter.limit, cursor: filter.cursor, include: filter.include }, ...signalOf(filter) }),
+    get: (id, options = {}) => this.call("GET", `${AGENT}/profiles/${segment(id)}`, signalOf(options)),
+    update: (id, patch, options = {}) => this.call("PATCH", `${AGENT}/profiles/${segment(id)}`, { body: patch, ...signalOf(options) }),
+    usage: (id, options = {}) => this.call("GET", `${AGENT}/profiles/${segment(id)}/usage`, { query: { limit: options.limit, cursor: options.cursor }, ...signalOf(options) }),
+    versions: (id, options = {}) => this.call("GET", `${AGENT}/profiles/${segment(id)}/versions`, { query: { limit: options.limit, cursor: options.cursor }, ...signalOf(options) }),
+    createVersion: (id, input, options = {}) => this.call("POST", `${AGENT}/profiles/${segment(id)}/versions`, { body: input, ...idempotent(options) }),
+    version: (id, version, options = {}) => this.call("GET", `${AGENT}/profiles/${segment(id)}/versions/${version}`, signalOf(options)),
+    skill: (id, version, name, options = {}) => this.call("GET", `${AGENT}/profiles/${segment(id)}/versions/${version}/skills/${segment(name)}`, signalOf(options)),
+    render: (id, version, name, params, options = {}) => this.call("POST", `${AGENT}/profiles/${segment(id)}/versions/${version}/commands/${segment(name)}/render`, { body: { params }, ...signalOf(options) }),
+    ofSession: (addr, options = {}) => this.call("GET", `${AGENT}/sessions/${segment(addr)}/profile`, signalOf(options)),
+    assign: (addr, input, options = {}) => this.call("PUT", `${AGENT}/sessions/${segment(addr)}/profile`, { body: input, ...signalOf(options) }),
+    unassign: (addr, expectedRevision, options = {}) => this.call("DELETE", `${AGENT}/sessions/${segment(addr)}/profile`, { query: { expectedRevision }, ...signalOf(options) }),
+    sessionSkill: (addr, name, options = {}) => this.call("GET", `${AGENT}/sessions/${segment(addr)}/profile/skills/${segment(name)}`, signalOf(options)),
+    sessionRender: (addr, name, params, options = {}) => this.call("POST", `${AGENT}/sessions/${segment(addr)}/profile/commands/${segment(name)}/render`, { body: { params }, ...signalOf(options) }),
+  }
+
+  /** Workspaces (HWA-06). */
+  readonly workspaces: Workspaces = {
+    create: (input, options = {}) => this.call("POST", `${AGENT}/workspaces`, { body: input, ...idempotent(options) }),
+    list: (filter = {}) => this.call("GET", `${AGENT}/workspaces`, { query: { state: filter.state, limit: filter.limit, cursor: filter.cursor }, ...signalOf(filter) }),
+    get: (id, options = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}`, signalOf(options)),
+    update: (id, patch, options = {}) => this.call("PATCH", `${AGENT}/workspaces/${segment(id)}`, { body: patch, ...signalOf(options) }),
+    archive: (id, expectedRevision, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/archive`, { body: { expectedRevision }, ...signalOf(options) }),
+    restore: (id, expectedRevision, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/restore`, { body: { expectedRevision }, ...signalOf(options) }),
+    bindings: (id, options = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/bindings`, signalOf(options)),
+    bind: (id, input, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/bindings`, { body: input, ...idempotent(options) }),
+    unbind: (id, bindingID, expectedRevision, options = {}) => this.call("DELETE", `${AGENT}/workspaces/${segment(id)}/bindings`, { query: { bindingID, expectedRevision }, ...signalOf(options) }),
+    members: (id, options = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/members`, { query: { includeLeft: options.includeLeft ? 1 : undefined }, ...signalOf(options) }),
+    join: (id, input, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/members`, { body: input, ...idempotent(options) }),
+    setRole: (id, memberID, role, expectedRevision, options = {}) => this.call("PATCH", `${AGENT}/workspaces/${segment(id)}/members/${segment(memberID)}`, { body: { role, expectedRevision }, ...signalOf(options) }),
+    leave: (id, memberID, expectedRevision, options = {}) => this.call("DELETE", `${AGENT}/workspaces/${segment(id)}/members/${segment(memberID)}`, { query: { expectedRevision }, ...signalOf(options) }),
+    assignments: (id, filter = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/assignments`, { query: { memberID: filter.memberID, status: filter.status, limit: filter.limit, cursor: filter.cursor }, ...signalOf(filter) }),
+    assignment: (id, assignmentID, options = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/assignments/${segment(assignmentID)}`, signalOf(options)),
+    assign: (id, input, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/assignments`, { body: input, ...idempotent(options) }),
+    setAssignmentStatus: (id, assignmentID, status, expectedRevision, options = {}) => this.call("PATCH", `${AGENT}/workspaces/${segment(id)}/assignments/${segment(assignmentID)}`, { body: { status, expectedRevision }, ...signalOf(options) }),
+    reassign: (id, assignmentID, memberID, expectedRevision, options = {}) => this.call("PATCH", `${AGENT}/workspaces/${segment(id)}/assignments/${segment(assignmentID)}`, { body: { memberID, expectedRevision }, ...signalOf(options) }),
+    supervision: (id, options = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/supervision`, signalOf(options)),
+    supervise: (id, input, options = {}) => this.call("PUT", `${AGENT}/workspaces/${segment(id)}/supervision`, { body: input, ...signalOf(options) }),
+    board: (id, options = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/board`, signalOf(options)),
+    master: (id, options = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/master`, signalOf(options)),
+    replaceMaster: (id, input, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/master`, { body: input, ...idempotent(options) }),
+    createSideChat: (id, input, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/side-chats`, { body: input, ...idempotent(options) }),
+    sideChats: (id, filter = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/side-chats`, { query: { limit: filter.limit, cursor: filter.cursor }, ...signalOf(filter) }),
+    sideChat: (id, sideChatID, options = {}) => this.call("GET", `${AGENT}/workspaces/${segment(id)}/side-chats/${segment(sideChatID)}`, signalOf(options)),
+    sideChatByID: (sideChatID, options = {}) => this.call("GET", `${AGENT}/side-chats/${segment(sideChatID)}`, signalOf(options)),
+    refreshSideChat: (id, sideChatID, expectedRevision, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/side-chats/${segment(sideChatID)}/refresh`, { body: { expectedRevision }, ...signalOf(options) }),
+    sendToMain: (id, sideChatID, text, options = {}) => this.call("POST", `${AGENT}/workspaces/${segment(id)}/side-chats/${segment(sideChatID)}/send`, { body: { text, confirmed: true }, ...signalOf(options) }),
+  }
+
+  /** Persistent artifacts (HWA-21): metadata as JSON, bytes inline when small or staged and referenced. */
+  readonly artifacts: Artifacts = artifactsApi(this)
+  /** Teams (HWA-37): definitions, drafts, staffing and status, plus intake (HWA-36): give work, read it, report status. */
+  readonly teams: Teams = teamsApi(this)
+  /** Concierge (CON-01): its watchlist (get, update, watch/unwatch, mute/unmute). */
+  readonly concierge: Concierge = conciergeApi(this)
+
   constructor(options: HubClientOptions) {
     this.url = options.url
     this.#base = options.url.replace(/\/+$/, "")
@@ -226,14 +432,15 @@ export class HubClient {
   /** Sends a request; resolves the response when OK, else throws HubError / HubTransportError. */
   async request(method: string, pathname: string, options: RequestOptions = {}): Promise<Response> {
     const target = `${pathname}${queryString(options.query)}`
-    const headers: Record<string, string> = { authorization: `Bearer ${this.#token}`, accept: "application/json" }
+    const headers: Record<string, string> = { ...options.headers, authorization: `Bearer ${this.#token}`, accept: "application/json" }
     if (options.body !== undefined) headers["content-type"] = "application/json"
+    if (options.raw) headers["content-type"] = options.raw.contentType
     let response: Response
     try {
       response = await this.#fetch(`${this.#base}${target}`, {
         method,
         headers,
-        ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+        ...(options.raw ? { body: options.raw.body } : options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
         redirect: "manual",
       })
@@ -282,7 +489,7 @@ export class HubClient {
   sessions(filter: SessionsFilter = {}): Promise<{ sessions: SessionView[] }> {
     const state = typeof filter.state === "string" ? filter.state : filter.state?.join(",")
     return this.call("GET", `${AGENT}/sessions`, {
-      query: { project: filter.project, state, machine: filter.machine, label: filter.label },
+      query: { project: filter.project, state, machine: filter.machine, label: filter.label, q: filter.q },
       ...signalOf(filter),
     })
   }
@@ -298,8 +505,8 @@ export class HubClient {
   }
 
   /** Named and role-holding sessions. */
-  who(options: CallOptions & { readonly project?: string; readonly role?: string } = {}): Promise<{ sessions: DirectoryEntry[] }> {
-    return this.call("GET", `${AGENT}/who`, { query: { project: options.project, role: options.role === undefined ? undefined : bareRole(options.role) }, ...signalOf(options) })
+  who(options: CallOptions & { readonly project?: string; readonly role?: string; readonly team?: string } = {}): Promise<WhoAnswer> {
+    return this.call("GET", `${AGENT}/who`, { query: { project: options.project, role: options.role === undefined ? undefined : bareRole(options.role), team: options.team }, ...signalOf(options) })
   }
 
   /**
@@ -355,6 +562,20 @@ export class HubClient {
     return this.call("PUT", `${AGENT}/sessions/${segment(addr)}/pin`, { body: { pinned }, ...signalOf(options) })
   }
 
+  /** (CON-02) A session's intent: the stored one, else its non-placeholder title (source title), else null. */
+  intent(addr: string, options: CallOptions = {}): Promise<{ intent: SessionIntent | null }> {
+    return this.call("GET", `${AGENT}/sessions/${segment(addr)}/intent`, signalOf(options))
+  }
+
+  /**
+   * (CON-02) Sets (text) or clears (null) the caller's intent layer under expectedRevision (the revision read;
+   * stale: conflict with currentRevision). Users and apps (sessions:manage) write source user, a session token its
+   * own session only (source self).
+   */
+  setIntent(addr: string, text: string | null, expectedRevision: number, options: CallOptions = {}): Promise<{ intent: SessionIntent | null }> {
+    return this.call("PUT", `${AGENT}/sessions/${segment(addr)}/intent`, { body: { text, expectedRevision }, ...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) })
   }

package/packages/sdk/src/concierge.ts

@@ -0,0 +1,88 @@
+// hub.concierge (CON-01) over /api/agent/concierge: the Concierge's watchlist — which of the user's sessions it
+// watches (auto-active sessions, the console's pins, explicit sessions, projects and launch-label filters, minus
+// mutes). Who: users; app tokens with sessions:read (get) or sessions:manage (update and the verbs); the user's current
+// Concierge session through its act token (get and the verbs only). Every other session token gets 404 (not_found).
+// `update` sends the revision you read (expectedRevision; 409 conflict with currentRevision when stale); the verbs are
+// idempotent (`changed: false` when nothing changed) and resolve the address for the caller (a subagent watches its
+// root). The wire types mirror the hub's protocol (packages/protocol/src/concierge.ts); the SDK imports nothing
+// outside its package.
+
+interface Signal {
+  readonly signal?: AbortSignal
+}
+
+export interface WatchlistConfig {
+  readonly autoActive: boolean
+  /** 1–24. */
+  readonly activeWithinHours: number
+  readonly usePins: boolean
+  /** Explicit ses_… IDs (≤ 200). */
+  readonly sessions: readonly string[]
+  /** Canonical absolute project directories (≤ 50). */
+  readonly projects: readonly string[]
+  /** ≤ 20 filters; each matches when all its pairs equal a launch's labels. */
+  readonly labels: readonly Readonly<Record<string, string>>[]
+  /** ses_… IDs (≤ 500); beats every include. */
+  readonly muted: readonly string[]
+  readonly mutedProjects: readonly string[]
+  readonly revision: number
+}
+
+export type WatchReason = "active" | "pinned" | "pinned_project" | "explicit" | "project" | "label"
+
+export interface WatchlistEntry {
+  readonly sessionID: string
+  readonly reasons: readonly WatchReason[]
+  readonly lastActiveAt?: number
+}
+
+export interface WatchlistView {
+  readonly config: WatchlistConfig
+  readonly entries: readonly WatchlistEntry[]
+  readonly truncated: boolean
+}
+
+/** What PUT takes: any of the config fields (revision is the server's). */
+export type WatchlistUpdate = Partial<Omit<WatchlistConfig, "revision">>
+
+/** The answer of the watch/unwatch/mute/unmute verbs: the stored config, the resolved root session, and whether it changed. */
+export interface WatchlistChanged {
+  readonly config: WatchlistConfig
+  readonly sessionID: string
+  readonly changed: boolean
+}
+
+export interface ConciergeWatchlistApi {
+  get(options?: Signal): Promise<WatchlistView>
+  update(patch: WatchlistUpdate, expectedRevision: number, options?: Signal): Promise<{ config: WatchlistConfig }>
+  watch(addr: string, options?: Signal): Promise<WatchlistChanged>
+  unwatch(addr: string, options?: Signal): Promise<WatchlistChanged>
+  mute(addr: string, options?: Signal): Promise<WatchlistChanged>
+  unmute(addr: string, options?: Signal): Promise<WatchlistChanged>
+}
+
+export interface Concierge {
+  readonly watchlist: ConciergeWatchlistApi
+}
+
+/** What hub.concierge needs from the client (HubClient's call). */
+export interface ConciergeTransport {
+  call<T>(method: string, pathname: string, options?: { readonly body?: unknown; readonly signal?: AbortSignal }): Promise<T>
+}
+
+const WATCHLIST = "/api/agent/concierge/watchlist"
+const sig = (options: Signal = {}) => (options.signal ? { signal: options.signal } : {})
+
+export function conciergeApi(hub: ConciergeTransport): Concierge {
+  const verb = (name: string) => (addr: string, options?: Signal) => hub.call<WatchlistChanged>("POST", `${WATCHLIST}/${name}`, { body: { session: addr }, ...sig(options) })
+  return {
+    watchlist: {
+      get: (options) => hub.call("GET", WATCHLIST, sig(options)),
+      update: (patch, expectedRevision, options) => hub.call("PUT", WATCHLIST, { body: { ...patch, expectedRevision }, ...sig(options) }),
+      watch: verb("watch"),
+      unwatch: verb("unwatch"),
+      mute: verb("mute"),
+      unmute: verb("unmute"),
+    },
+  }
+}

package/packages/sdk/src/errors.ts

@@ -14,6 +14,7 @@ export type ErrorCode =
   | "not_found"
   | "ambiguous"
   | "name_taken"
+  | "conflict"
   | "gone"
   | "unsupported"
   | "paused"
@@ -28,7 +29,8 @@ export interface Envelope {
   readonly hint?: string
   /**
    * More fields, by code: candidates (ambiguous), retryAfter (rate_limited, seconds), feature/harness (unsupported),
-   * evaluation/decisionID (needs_user; see needsUserOf).
+   * evaluation/decisionID (needs_user; see needsUserOf),
+   * currentRevision (conflict).
    */
   readonly [extra: string]: unknown
 }

package/packages/sdk/src/index.ts

@@ -2,7 +2,12 @@
 // errors (HubError, HubTransportError), the answer types, the SSE parser of the watch stream, and the pure
 // envelope renderer/sanitiser and address parser shared with the hub, launches, and webhook verification.
 export * from "./address.ts"
+export * from "./artifacts.ts"
+export * from "./artifact-jobs.ts"
+export * from "./team-intake.ts"
+export * from "./teams.ts"
 export * from "./client.ts"
+export * from "./concierge.ts"
 export * from "./envelope.ts"
 export * from "./errors.ts"
 export * from "./sse.ts"

package/packages/sdk/src/team-intake.ts

@@ -0,0 +1,122 @@
+// hub.teams intake verbs (HWA-36) over /api/agent/teams/:id/intake: give work to a team (its entry role receives it
+// as a hub message and owns it as a workspace assignment), read it back, and report status explicitly. Users; app
+// tokens with teams:submit (submit, read and cancel their own submissions); session tokens (submit under team policy;
+// sessions in the team's entry role report progress). Definitions, staffing and the rest of hub.teams are HWA-37's.
+// The wire type mirrors the hub's StoredIntake (packages/protocol TeamIntake plus additive fields; the SDK imports
+// nothing outside its package; the hub's tests keep them in step).
+
+interface Signal {
+  readonly signal?: AbortSignal
+}
+
+export type TeamIntakeStatus = "queued" | "routed" | "done" | "cancelled" | "failed"
+export type TeamIntakePriority = "low" | "normal" | "high" | "urgent"
+export type TeamIntakeProgress = "open" | "in_progress" | "blocked"
+/** What setIntakeStatus accepts: progress while routed, or a closing status (submitters: cancelled only). */
+export type TeamIntakeStatusInput = TeamIntakeProgress | "done" | "failed" | "cancelled"
+
+export interface TeamIntake {
+  readonly v: 1
+  readonly id: string
+  readonly teamID: string
+  readonly title: string
+  readonly source: { readonly kind: "user" } | { readonly kind: "app"; readonly tokenID: string } | { readonly kind: "session"; readonly sessionID: string }
+  readonly ref?: string
+  readonly assignmentID?: string
+  readonly status: TeamIntakeStatus
+  readonly revision: number
+  readonly createdAt: number
+  readonly priority: TeamIntakePriority
+  readonly labels?: readonly string[]
+  /** Epoch ms. */
+  readonly due?: number
+  readonly criteria?: readonly string[]
+  readonly workspaceID?: string
+  readonly sessionID?: string
+  readonly messageID?: string
+  readonly progress?: TeamIntakeProgress
+  readonly reason?: string
+  readonly lastError?: string
+  readonly updatedAt: number
+  readonly routedAt?: number
+  readonly closedAt?: number
+}
+
+export interface TeamIntakeSubmit {
+  readonly title: string
+  /** Delivered in the message only; never stored after delivery, never in events. */
+  readonly brief?: string
+  readonly priority?: TeamIntakePriority
+  readonly labels?: readonly string[]
+  /** Epoch ms. */
+  readonly due?: number
+  readonly criteria?: readonly string[]
+  /** An external reference (e.g. a Brain task ID). */
+  readonly ref?: string
+}
+
+/** The assignment a status change moved (as hub.workspaces shows it). */
+export interface TeamIntakeAssignment {
+  readonly id: string
+  readonly workspaceID: string
+  readonly memberID: string
+  readonly status: "open" | "in_progress" | "blocked" | "done" | "cancelled"
+  readonly revision: number
+}
+
+export interface TeamIntakeApi {
+  /** Submits work; `created` false for an Idempotency-Key replay. Queued while the entry role is vacant. */
+  submit(team: string, input: TeamIntakeSubmit, options?: Signal & { readonly idempotencyKey?: string }): Promise<{ intake: TeamIntake; created: boolean }>
+  intake(team: string, intakeID: string, options?: Signal): Promise<{ intake: TeamIntake }>
+  intakes(team: string, filter?: Signal & { readonly status?: TeamIntakeStatus; readonly limit?: number; readonly cursor?: string }): Promise<{ items: readonly TeamIntake[]; cursor?: string }>
+  setIntakeStatus(
+    team: string,
+    intakeID: string,
+    input: { readonly status: TeamIntakeStatusInput; readonly expectedRevision: number; readonly reason?: string },
+    options?: Signal,
+  ): Promise<{ intake: TeamIntake; assignment?: TeamIntakeAssignment }>
+}
+
+type Query = Readonly<Record<string, string | number | undefined>>
+
+/** What hub.teams needs from the client (HubClient's request and call). */
+export interface TeamIntakeTransport {
+  request(method: string, pathname: string, options?: { readonly query?: Query; readonly body?: unknown; readonly headers?: Readonly<Record<string, string>>; readonly signal?: AbortSignal }): Promise<Response>
+  call<T>(method: string, pathname: string, options?: { readonly query?: Query; readonly body?: unknown; readonly signal?: AbortSignal }): Promise<T>
+}
+
+const seg = (value: string) => encodeURIComponent(value)
+const sig = (options: Signal = {}) => (options.signal ? { signal: options.signal } : {})
+const path = (team: string) => `/api/agent/teams/${seg(team)}/intake`
+
+export function teamIntakeApi(hub: TeamIntakeTransport): TeamIntakeApi {
+  return {
+    submit: async (team, input, options = {}) => {
+      const response = await hub.request("POST", path(team), { body: input, ...(options.idempotencyKey ? { headers: { "idempotency-key": options.idempotencyKey } } : {}), ...sig(options) })
+      const answer = (await response.json()) as { intake: TeamIntake }
+      return { intake: answer.intake, created: response.status === 201 }
+    },
+    intake: (team, intakeID, options) => hub.call("GET", `${path(team)}/${seg(intakeID)}`, sig(options)),
+    intakes: (team, filter = {}) => hub.call("GET", path(team), { query: { status: filter.status, limit: filter.limit, cursor: filter.cursor }, ...sig(filter) }),
+    setIntakeStatus: (team, intakeID, input, options) => hub.call("POST", `${path(team)}/${seg(intakeID)}/status`, { body: input, ...sig(options) }),
+  }
+}
+
+/** Every status setIntakeStatus accepts, in the order tools list them. */
+export const TEAM_INTAKE_STATUS_INPUTS: readonly TeamIntakeStatusInput[] = ["open", "in_progress", "blocked", "done", "failed", "cancelled"]
+
+/**
+ * Reports an intake item's status (the entry role's progress or closing, a submitter's cancel). Without
+ * `expectedRevision` the item is read first and its current revision sent: a change in between is still a conflict.
+ * Authority is the hub's (the route's rules); nothing is decided here.
+ */
+export async function reportIntakeStatus(
+  api: Pick<TeamIntakeApi, "intake" | "setIntakeStatus">,
+  team: string,
+  intakeID: string,
+  input: { readonly status: TeamIntakeStatusInput; readonly expectedRevision?: number; readonly reason?: string },
+  options: Signal = {},
+): Promise<{ intake: TeamIntake; assignment?: TeamIntakeAssignment }> {
+  const expectedRevision = input.expectedRevision ?? (await api.intake(team, intakeID, options)).intake.revision
+  return api.setIntakeStatus(team, intakeID, { status: input.status, expectedRevision, ...(input.reason !== undefined ? { reason: input.reason } : {}) }, options)
+}