From 0a9337d2bb219e3096a3707ca143968dc4bcc005 Mon Sep 17 00:00:00 2001
From: Adolanium <94890352+Adolanium@users.noreply.github.com>
Date: Sun, 16 Aug 2026 11:30:27 +0300
Subject: [PATCH] feat(desktop): expose busy turn flags on plugin SDK

Plugins can now read host.state.busy and host.state.awaitingResponse
for the focused chat. These follow the same session slice the chat pane
uses, so a draft falls back to the global flags and a background turn
does not leak.
---
 apps/desktop/src/plugins/example/plugin.tsx   |  3 +-
 apps/desktop/src/sdk/index.test.ts            | 66 +++++++++++++++++++
 apps/desktop/src/sdk/index.ts                 |  9 +++
 .../references/desktop-plugins.md             |  8 ++-
 .../developer-guide/desktop-plugin-sdk.md     | 13 ++++
 5 files changed, 95 insertions(+), 4 deletions(-)
 create mode 100644 apps/desktop/src/sdk/index.test.ts

diff --git a/apps/desktop/src/plugins/example/plugin.tsx b/apps/desktop/src/plugins/example/plugin.tsx
index 7d13206784..f4c1ee1187 100644
--- a/apps/desktop/src/plugins/example/plugin.tsx
+++ b/apps/desktop/src/plugins/example/plugin.tsx
@@ -39,10 +39,11 @@ const $events = atom(0)
 function ClickCounter() {
   const count = useValue($clicks)
   const events = useValue($events)
+  const busy = useValue(host.state.busy)
   const gateway = useValue(host.state.gateway)
 
   return (
-    <Tip label={`Example plugin — gateway ${gateway}, ${events} events heard`}>
+    <Tip label={`Example plugin: gateway ${gateway}, ${busy ? 'working' : 'idle'}, ${events} events heard`}>
       <button
         className={cn(
           'inline-flex h-full items-center gap-1 rounded-none px-1.5 text-[0.6875rem] tabular-nums transition-colors',
diff --git a/apps/desktop/src/sdk/index.test.ts b/apps/desktop/src/sdk/index.test.ts
new file mode 100644
index 0000000000..21b93df60e
--- /dev/null
+++ b/apps/desktop/src/sdk/index.test.ts
@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { createClientSessionState } from '@/lib/chat-runtime'
+import { host } from '@/sdk'
+import {
+  setActiveSessionId,
+  setAwaitingResponse,
+  setBusy
+} from '@/store/session'
+import { clearAllSessionStates, publishSessionState } from '@/store/session-states'
+
+describe('host.state turn flags', () => {
+  afterEach(() => {
+    setActiveSessionId(null)
+    setBusy(false)
+    setAwaitingResponse(false)
+    clearAllSessionStates()
+  })
+
+  it('uses the draft atoms when there is no runtime session', () => {
+    expect(host.state.busy.get()).toBe(false)
+    expect(host.state.awaitingResponse.get()).toBe(false)
+
+    setBusy(true)
+    setAwaitingResponse(true)
+
+    expect(host.state.busy.get()).toBe(true)
+    expect(host.state.awaitingResponse.get()).toBe(true)
+  })
+
+  it('reads the focused session slice once a runtime exists', () => {
+    setBusy(false)
+    setAwaitingResponse(false)
+    setActiveSessionId('rt-focus')
+    publishSessionState('rt-focus', {
+      ...createClientSessionState('stored-focus'),
+      awaitingResponse: true,
+      busy: true
+    })
+
+    expect(host.state.busy.get()).toBe(true)
+    expect(host.state.awaitingResponse.get()).toBe(true)
+
+    publishSessionState('rt-focus', {
+      ...createClientSessionState('stored-focus'),
+      awaitingResponse: false,
+      busy: true
+    })
+
+    expect(host.state.busy.get()).toBe(true)
+    expect(host.state.awaitingResponse.get()).toBe(false)
+  })
+
+  it('does not pick up a background session', () => {
+    setActiveSessionId('rt-focus')
+    publishSessionState('rt-focus', createClientSessionState('stored-focus'))
+    publishSessionState('rt-bg', {
+      ...createClientSessionState('stored-bg'),
+      awaitingResponse: true,
+      busy: true
+    })
+
+    expect(host.state.busy.get()).toBe(false)
+    expect(host.state.awaitingResponse.get()).toBe(false)
+  })
+})
diff --git a/apps/desktop/src/sdk/index.ts b/apps/desktop/src/sdk/index.ts
index 2ad2e22bdf..330c53d1b7 100644
--- a/apps/desktop/src/sdk/index.ts
+++ b/apps/desktop/src/sdk/index.ts
@@ -20,6 +20,7 @@
 
 import { atom, type ReadableAtom } from 'nanostores'
 
+import { PRIMARY_SESSION_VIEW } from '@/app/chat/session-view'
 import { openSession, type OpenSessionIntent } from '@/app/open-session'
 import { $narrowViewport } from '@/components/pane-shell/tree/store'
 import { onGatewayEvent } from '@/contrib/events'
@@ -69,6 +70,14 @@ export const host = {
   state: {
     /** Runtime id of the active chat session (null on a fresh draft). */
     activeSessionId: readonlyAtom<null | string>($activeSessionId),
+    /** True from send until the first assistant payload on the focused chat. */
+    awaitingResponse: readonlyAtom<boolean>(PRIMARY_SESSION_VIEW.$awaitingResponse),
+    /**
+     * True while the focused chat is working after a send. Covers the wait
+     * for the first token and the stream that follows. Same session as
+     * `activeSessionId`. A draft with no runtime id uses the global flag.
+     */
+    busy: readonlyAtom<boolean>(PRIMARY_SESSION_VIEW.$busy),
     /** Active workspace cwd ('' when detached). */
     cwd: readonlyAtom<string>($currentCwd),
     /** Gateway socket state: 'idle' | 'connecting' | 'open' | …. */
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md b/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
index 3c24db3b4d..c9cb78a213 100644
--- a/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
@@ -54,9 +54,11 @@ The ONLY import surface is `@hermes/plugin-sdk` (plus `react` /
 `react/jsx-runtime`, which resolve to the app's own React — write UI with
 `jsx()` calls, not JSX syntax; the file is not compiled).
 
-- `host.state.*` — readonly reactive atoms: `activeSessionId`, `cwd`,
-  `gateway`, `model`, `profile`, `viewport`. Read with `.get()` in handlers,
-  `useValue(atom)` in components.
+- `host.state.*` — readonly reactive atoms: `activeSessionId`, `busy`,
+  `awaitingResponse`, `cwd`, `gateway`, `model`, `profile`, `viewport`.
+  `busy` is true while the focused chat is working after a send (thinking
+  and streaming). `awaitingResponse` is true until the first assistant
+  payload. Read with `.get()` in handlers, `useValue(atom)` in components.
 - `host.request(method, params)` — gateway JSON-RPC (sessions, config,
   skills, cron — everything the app uses).
 - `host.onEvent(type, fn)` — live gateway events (`'*'` for all). Returns a
diff --git a/website/docs/developer-guide/desktop-plugin-sdk.md b/website/docs/developer-guide/desktop-plugin-sdk.md
index 73973aa24b..c120f2d138 100644
--- a/website/docs/developer-guide/desktop-plugin-sdk.md
+++ b/website/docs/developer-guide/desktop-plugin-sdk.md
@@ -374,6 +374,8 @@ components.
 
 ```ts
 host.state.activeSessionId  // ReadableAtom<string | null>
+host.state.awaitingResponse // ReadableAtom<boolean>  true until the first assistant payload
+host.state.busy             // ReadableAtom<boolean>  focused chat is working after a send
 host.state.cwd              // ReadableAtom<string>
 host.state.gateway          // ReadableAtom<string>  ('idle' | 'connecting' | 'open' | …)
 host.state.model            // ReadableAtom<string>
@@ -405,6 +407,17 @@ cron, kanban, …). Profile-shaped plugins get first-class methods too:
 probe) and `profiles.create` (`name`, `description`, `clone_from`,
 `clone_all`, `no_skills`, `soul`, optional `model` + `provider` pin) — the
 ws twins of the dashboard's `/api/profiles` REST routes.
+`host.state.busy` is the focused chat's live turn (thinking and streaming).
+`host.state.awaitingResponse` stays true from send until the first assistant
+payload. Both follow `activeSessionId`. Subscribe in a component:
+
+```javascript
+const busy = useValue(host.state.busy)
+```
+
+For token-level detail, listen with `host.onEvent` (`message.start`,
+`message.delta`, `message.complete`).
+
 `host.onEvent` streams live gateway events (message deltas,
 session lifecycle, tool activity). Listeners are isolated — a throw in your
 listener can't affect app dispatch. Every `host` door is async-safe: a sync throw