@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/apps/desktop/src/lib/desktop-slash-commands.ts

@@ -22,109 +22,168 @@ export interface DesktopThemeCommandOption {
   name: string
 }
 
-const DESKTOP_COMMAND_META = [
-  ['/agents', 'Show active desktop sessions and running tasks'],
-  ['/background', 'Run a prompt in the background'],
-  ['/branch', 'Branch the latest message into a new chat'],
-  ['/compress', 'Compress this conversation context'],
-  ['/debug', 'Create a debug report'],
-  ['/goal', 'Manage the standing goal for this session'],
-  ['/help', 'Show desktop slash commands'],
-  ['/new', 'Start a new desktop chat'],
-  ['/queue', 'Queue a prompt for the next turn'],
-  ['/resume', 'Resume a saved session'],
-  ['/retry', 'Retry the last user message'],
-  ['/rollback', 'List or restore filesystem checkpoints'],
-  ['/skin', 'Switch desktop theme or cycle to the next one'],
-  ['/status', 'Show current session status'],
-  ['/steer', 'Steer the current run after the next tool call'],
-  ['/stop', 'Stop running background processes'],
-  ['/title', 'Rename the current session'],
-  ['/undo', 'Remove the last user/assistant exchange'],
-  ['/usage', 'Show token usage for this session']
-] as const
-
-const DESKTOP_COMMANDS: ReadonlySet<string> = new Set(DESKTOP_COMMAND_META.map(([command]) => command))
-
-const DESKTOP_ALIASES = new Map([
-  ['/bg', '/background'],
-  ['/btw', '/background'],
-  ['/fork', '/branch'],
-  ['/q', '/queue'],
-  ['/reload_mcp', '/reload-mcp'],
-  ['/reload_skills', '/reload-skills'],
-  ['/reset', '/new'],
-  ['/tasks', '/agents']
-])
-
-const DESKTOP_COMMAND_DESCRIPTIONS: ReadonlyMap<string, string> = new Map(DESKTOP_COMMAND_META)
-
-const PICKER_OWNED_COMMANDS = new Set(['/model'])
-
-const TERMINAL_ONLY_COMMANDS = new Set([
-  '/browser',
-  '/busy',
-  '/clear',
-  '/commands',
-  '/compact',
-  '/config',
-  '/copy',
-  '/cron',
-  '/details',
-  '/exit',
-  '/footer',
-  '/gateway',
-  '/gquota',
-  '/history',
-  '/image',
-  '/indicator',
-  '/logs',
-  '/mouse',
-  '/paste',
-  '/platforms',
-  '/plugins',
-  '/quit',
-  '/redraw',
-  '/reload',
-  '/restart',
-  '/save',
-  '/sb',
-  '/set-home',
-  '/sethome',
-  '/snap',
-  '/snapshot',
-  '/statusbar',
-  '/toolsets',
-  '/tools',
-  '/update',
-  '/verbose'
-])
-
-const MESSAGING_ONLY_COMMANDS = new Set(['/approve', '/deny'])
-
-const SETTINGS_OWNED_COMMANDS = new Set(['/skills'])
-
-const ADVANCED_COMMANDS = new Set([
-  '/curator',
-  '/fast',
-  '/insights',
-  '/kanban',
-  '/personality',
-  '/profile',
-  '/reasoning',
-  '/reload-mcp',
-  '/reload-skills',
-  '/voice',
-  '/yolo'
-])
-
-const BLOCKED_COMMANDS = new Set([
-  ...PICKER_OWNED_COMMANDS,
-  ...TERMINAL_ONLY_COMMANDS,
-  ...MESSAGING_ONLY_COMMANDS,
-  ...SETTINGS_OWNED_COMMANDS,
-  ...ADVANCED_COMMANDS
-])
+/**
+ * Local client action a command resolves to. Each id maps to exactly one
+ * handler in the dispatcher (`use-prompt-actions`), so adding a command never
+ * means adding a branch to a switch ladder — you add a row here + a handler
+ * keyed by the id.
+ */
+export type DesktopActionId =
+  | 'branch'
+  | 'browser'
+  | 'handoff'
+  | 'help'
+  | 'new'
+  | 'profile'
+  | 'skin'
+  | 'title'
+  | 'yolo'
+
+/** A command fulfilled by opening a desktop overlay picker. */
+export type DesktopPickerId = 'model' | 'session'
+
+/** Why a known Hermes command has no desktop UI surface. */
+export type DesktopUnavailableReason = 'advanced' | 'messaging' | 'settings' | 'terminal'
+
+/**
+ * How the desktop fulfils a command. This is the single discriminator the
+ * dispatcher, popover, pills, and pickers all read — no parallel block-lists.
+ *
+ * - `action`     → handled by a local client handler (new chat, branch, …)
+ * - `picker`     → opens an overlay (`/model`, `/resume`); a typed arg is
+ *                  resolved by that picker instead of falling through
+ * - `exec`       → runs on the backend via slash.exec / command.dispatch and
+ *                  renders its text output inline
+ * - `unavailable`→ a known command with genuinely no desktop UI (terminal-only,
+ *                  messaging-only, …); shows a reason instead of executing
+ */
+export type DesktopCommandSurface =
+  | { kind: 'action'; action: DesktopActionId }
+  | { kind: 'picker'; picker: DesktopPickerId }
+  | { kind: 'exec' }
+  | { kind: 'unavailable'; reason: DesktopUnavailableReason }
+
+export interface DesktopCommandSpec {
+  /** Canonical command, leading slash included (e.g. `/resume`). */
+  name: string
+  /** Popover/help label; omitted for unavailable commands (never surfaced). */
+  description?: string
+  aliases?: string[]
+  surface: DesktopCommandSurface
+  /**
+   * Hide from the slash popover / completions while still letting it execute.
+   * Used for picker commands reachable from chrome (the model picker lives on
+   * the status bar), so the popover doesn't dead-end on inline completion.
+   */
+  hidden?: boolean
+  /**
+   * The command has an inline options "screen" (theme / personality / session /
+   * platform / toolset list). Picking the bare command in the popover expands to
+   * that argument step instead of committing — mirroring typing `/<cmd> ` by hand.
+   */
+  args?: boolean
+}
+
+const exec = (): DesktopCommandSurface => ({ kind: 'exec' })
+const action = (id: DesktopActionId): DesktopCommandSurface => ({ kind: 'action', action: id })
+const picker = (id: DesktopPickerId): DesktopCommandSurface => ({ kind: 'picker', picker: id })
+const unavailable = (reason: DesktopUnavailableReason): DesktopCommandSurface => ({ kind: 'unavailable', reason })
+
+/**
+ * THE source of truth for desktop slash commands. Everything below — execution
+ * gating, popover suggestions, catalog filtering, pill grouping, and the
+ * dispatcher's behavior — derives from this one table.
+ */
+const DESKTOP_COMMAND_SPECS: readonly DesktopCommandSpec[] = [
+  // Local client actions
+  { name: '/new', description: 'Start a new desktop chat', aliases: ['/reset'], surface: action('new') },
+  { name: '/branch', description: 'Branch the latest message into a new chat', aliases: ['/fork'], surface: action('branch') },
+  { name: '/yolo', description: 'Toggle YOLO — auto-approve dangerous commands', surface: action('yolo') },
+  { name: '/handoff', description: 'Hand off this session to a messaging platform', surface: action('handoff'), args: true },
+  { name: '/profile', description: 'Switch the active Hermes profile', surface: action('profile') },
+  { name: '/skin', description: 'Switch desktop theme or cycle to the next one', surface: action('skin'), args: true },
+  { name: '/title', description: 'Rename the current session', surface: action('title') },
+  { name: '/help', description: 'Show desktop slash commands', aliases: ['/commands'], surface: action('help') },
+  {
+    name: '/browser',
+    description: 'Manage browser CDP connection [connect|disconnect|status] (local gateway only)',
+    surface: action('browser'),
+    args: true
+  },
+
+  // Overlay pickers
+  { name: '/model', description: 'Switch the model for this session', surface: picker('model'), hidden: true },
+  {
+    name: '/resume',
+    description: 'Resume a saved session',
+    aliases: ['/sessions', '/switch'],
+    surface: picker('session'),
+    args: true
+  },
+
+  // Backend-executed commands that render useful inline output
+  { name: '/agents', description: 'Show active desktop sessions and running tasks', aliases: ['/tasks'], surface: exec() },
+  { name: '/background', description: 'Run a prompt in the background', aliases: ['/bg', '/btw'], surface: exec() },
+  { name: '/compress', description: 'Compress this conversation context', surface: exec() },
+  { name: '/debug', description: 'Create a debug report', surface: exec() },
+  { name: '/goal', description: 'Manage the standing goal for this session', surface: exec() },
+  { name: '/personality', description: 'Switch personality for this session', surface: exec(), args: true },
+  { name: '/queue', description: 'Queue a prompt for the next turn', aliases: ['/q'], surface: exec() },
+  { name: '/retry', description: 'Retry the last user message', surface: exec() },
+  { name: '/rollback', description: 'List or restore filesystem checkpoints', surface: exec() },
+  { name: '/save', description: 'Save the current transcript to JSON', surface: exec() },
+  { name: '/status', description: 'Show current session status', surface: exec() },
+  { name: '/steer', description: 'Steer the current run after the next tool call', surface: exec() },
+  { name: '/stop', description: 'Stop running background processes', surface: exec() },
+  { name: '/tools', description: 'List or toggle tools available to the agent', surface: exec(), args: true },
+  { name: '/undo', description: 'Remove the last user/assistant exchange', surface: exec() },
+  { name: '/usage', description: 'Show token usage for this session', surface: exec() },
+  { name: '/version', description: 'Show Hermes Agent version', surface: exec() },
+
+  // No desktop surface, but carry an alias (underscore spelling variants).
+  { name: '/reload-mcp', aliases: ['/reload_mcp'], surface: unavailable('advanced') },
+  { name: '/reload-skills', aliases: ['/reload_skills'], surface: unavailable('advanced') }
+]
+
+// Known commands with no desktop surface (and no alias) — a flat name list
+// per reason beats 40 identical object literals.
+const NO_DESKTOP_SURFACE: Record<DesktopUnavailableReason, readonly string[]> = {
+  terminal: [
+    '/busy', '/clear', '/compact', '/config', '/copy', '/cron', '/details',
+    '/exit', '/footer', '/gateway', '/gquota', '/history', '/image', '/indicator', '/logs',
+    '/mouse', '/paste', '/platforms', '/plugins', '/quit', '/redraw', '/reload', '/restart',
+    '/sb', '/set-home', '/sethome', '/snap', '/snapshot', '/statusbar', '/toolsets', '/update', '/verbose'
+  ],
+  messaging: ['/approve', '/deny'],
+  settings: ['/skills'],
+  advanced: ['/curator', '/fast', '/insights', '/kanban', '/reasoning', '/voice']
+}
+
+const ALL_SPECS: readonly DesktopCommandSpec[] = [
+  ...DESKTOP_COMMAND_SPECS,
+  ...(Object.entries(NO_DESKTOP_SURFACE) as [DesktopUnavailableReason, readonly string[]][]).flatMap(
+    ([reason, names]) => names.map(name => ({ name, surface: unavailable(reason) }))
+  )
+]
+
+const SPEC_BY_NAME = new Map<string, DesktopCommandSpec>(ALL_SPECS.map(spec => [spec.name, spec]))
+
+const ALIAS_TO_CANONICAL = new Map<string, string>(
+  ALL_SPECS.flatMap(spec => (spec.aliases ?? []).map(alias => [alias, spec.name] as const))
+)
+
+const UNAVAILABLE_MESSAGE: Record<DesktopUnavailableReason, (command: string) => string> = {
+  advanced: command =>
+    `${command} is not shown in the desktop slash palette. Use the relevant desktop control or terminal interface instead.`,
+  messaging: command => `${command} is only used from messaging platforms.`,
+  settings: command => `${command} is managed from the desktop sidebar.`,
+  terminal: command => `${command} is only available in the terminal interface.`
+}
+
+const PICKER_UNAVAILABLE_MESSAGE: Record<DesktopPickerId, (command: string) => string> = {
+  model: command => `${command} uses the desktop model picker instead of a slash command.`,
+  session: command => `${command} uses the desktop session picker instead of a slash command.`
+}
 
 function normalizeCommand(command: string): string {
   const trimmed = command.trim()
@@ -136,58 +195,115 @@ function normalizeCommand(command: string): string {
 export function canonicalDesktopSlashCommand(command: string): string {
   const normalized = normalizeCommand(command)
 
-  return DESKTOP_ALIASES.get(normalized) || normalized
+  return ALIAS_TO_CANONICAL.get(normalized) || normalized
 }
 
-export function isDesktopSlashCommand(command: string): boolean {
+/** Resolve a command (or alias) to its desktop spec, or null for unknown/extension commands. */
+export function resolveDesktopCommand(command: string): DesktopCommandSpec | null {
+  return SPEC_BY_NAME.get(canonicalDesktopSlashCommand(command)) ?? null
+}
+
+function isKnownHermesSlashCommand(command: string): boolean {
+  const normalized = normalizeCommand(command)
+
+  return SPEC_BY_NAME.has(normalized) || ALIAS_TO_CANONICAL.has(normalized)
+}
+
+/**
+ * An "extension" command is anything the backend surfaces that is NOT one of
+ * Hermes' built-in slash commands — i.e. skill commands (`/gif-search`,
+ * `/codex`, …) and user-defined quick commands. These are user-activated, so
+ * they appear in the desktop slash palette and execute when typed.
+ */
+export function isDesktopSlashExtensionCommand(command: string): boolean {
   const normalized = normalizeCommand(command)
-  const canonical = canonicalDesktopSlashCommand(normalized)
 
-  if (BLOCKED_COMMANDS.has(normalized) || BLOCKED_COMMANDS.has(canonical)) {
+  if (!normalized || normalized === '/') {
     return false
   }
 
-  return DESKTOP_COMMANDS.has(canonical) || !isKnownHermesSlashCommand(normalized)
+  return !isKnownHermesSlashCommand(normalized)
 }
 
-export function isDesktopSlashSuggestion(command: string): boolean {
-  const normalized = normalizeCommand(command)
-  const canonical = canonicalDesktopSlashCommand(normalized)
+/** Gates execution: true unless the command is a known no-desktop-surface command. */
+export function isDesktopSlashCommand(command: string): boolean {
+  const spec = resolveDesktopCommand(command)
 
-  return DESKTOP_COMMANDS.has(canonical) && !DESKTOP_ALIASES.has(normalized)
+  if (spec) {
+    return spec.surface.kind !== 'unavailable'
+  }
+
+  return isDesktopSlashExtensionCommand(command)
 }
 
-export function desktopSlashUnavailableMessage(command: string): string | null {
+/** Gates discovery in the popover/completions. */
+export function isDesktopSlashSuggestion(command: string): boolean {
   const normalized = normalizeCommand(command)
-  const canonical = canonicalDesktopSlashCommand(normalized)
 
-  if (PICKER_OWNED_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} uses the desktop model picker instead of a slash command.`
+  // Aliases stay hidden so the popover isn't cluttered with duplicates.
+  if (ALIAS_TO_CANONICAL.has(normalized)) {
+    return false
+  }
+
+  const spec = SPEC_BY_NAME.get(normalized)
+
+  if (spec) {
+    return spec.surface.kind !== 'unavailable' && !spec.hidden
   }
 
-  if (SETTINGS_OWNED_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} is managed from the desktop sidebar.`
+  // Skill / quick commands the backend provides.
+  return isDesktopSlashExtensionCommand(normalized)
+}
+
+/**
+ * True for commands the desktop fulfils by opening an overlay picker
+ * (`/model`, `/resume`/`/sessions`/`/switch`). Optionally pin to one picker.
+ */
+export function isPickerCommand(command: string, picker?: DesktopPickerId): boolean {
+  const surface = resolveDesktopCommand(command)?.surface
+
+  if (surface?.kind !== 'picker') {
+    return false
   }
 
-  if (MESSAGING_ONLY_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} is only used from messaging platforms.`
+  return picker ? surface.picker === picker : true
+}
+
+/** Back-compat shim for the model picker check. */
+export function isModelPickerCommand(command: string): boolean {
+  return isPickerCommand(command, 'model')
+}
+
+export function desktopSlashUnavailableMessage(command: string): string | null {
+  const canonical = canonicalDesktopSlashCommand(command)
+  const surface = SPEC_BY_NAME.get(canonical)?.surface
+
+  if (!surface) {
+    return null
   }
 
-  if (ADVANCED_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} is not shown in the desktop slash palette. Use the relevant desktop control or terminal interface instead.`
+  if (surface.kind === 'unavailable') {
+    return UNAVAILABLE_MESSAGE[surface.reason](canonical)
   }
 
-  if (TERMINAL_ONLY_COMMANDS.has(normalized) || TERMINAL_ONLY_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} is only available in the terminal interface.`
+  if (surface.kind === 'picker') {
+    return PICKER_UNAVAILABLE_MESSAGE[surface.picker](canonical)
   }
 
   return null
 }
 
 export function desktopSlashDescription(command: string, fallback = ''): string {
-  const canonical = canonicalDesktopSlashCommand(command)
+  return SPEC_BY_NAME.get(canonicalDesktopSlashCommand(command))?.description || fallback
+}
 
-  return DESKTOP_COMMAND_DESCRIPTIONS.get(canonical) || fallback
+/**
+ * True when picking the bare command should expand to its inline argument
+ * options (theme / personality / session / platform / toolset) rather than
+ * committing immediately. Lets the popover act as a two-step picker.
+ */
+export function desktopSlashCommandTakesArgs(command: string): boolean {
+  return resolveDesktopCommand(command)?.args ?? false
 }
 
 export function desktopSkinSlashCompletions(
@@ -236,13 +352,36 @@ export function filterDesktopCommandsCatalog(catalog: CommandsCatalogLike): Comm
     ?.filter(([command]) => isDesktopSlashSuggestion(command))
     .map(([command, description]) => [command, desktopSlashDescription(command, description)] as [string, string])
 
+  // Recount skill commands from the filtered output so /help's footer reflects
+  // what the user actually sees. Backend's skill_count includes commands the
+  // desktop hides (terminal-only, picker-owned, advanced), producing a footer
+  // like "60 skill commands available" while only ~29 appear in the list.
+  const filteredCommands = new Set<string>()
+
+  for (const section of categories ?? []) {
+    for (const [command] of section.pairs) {
+      filteredCommands.add(canonicalDesktopSlashCommand(command))
+    }
+  }
+
+  for (const [command] of pairs ?? []) {
+    filteredCommands.add(canonicalDesktopSlashCommand(command))
+  }
+
+  let skillCount = 0
+
+  for (const command of filteredCommands) {
+    if (isDesktopSlashExtensionCommand(command)) {
+      skillCount += 1
+    }
+  }
+
+  const hasSkillCount = catalog.skill_count !== undefined || skillCount > 0
+
   return {
     ...catalog,
     ...(categories ? { categories } : {}),
-    ...(pairs ? { pairs } : {})
+    ...(pairs ? { pairs } : {}),
+    ...(hasSkillCount ? { skill_count: skillCount } : {})
   }
 }
-
-function isKnownHermesSlashCommand(command: string): boolean {
-  return DESKTOP_COMMANDS.has(command) || DESKTOP_ALIASES.has(command) || BLOCKED_COMMANDS.has(command)
-}

package/agent/apps/desktop/src/lib/external-link.test.tsx

@@ -165,4 +165,31 @@ describe('external link helpers', () => {
       'https://expedia.com/things-to-do/puerto-rico-el-yunque-rainforest-adventure'
     )
   })
+
+  it('explicitOnly skips bare filename/domain tokens and only links explicit URLs', () => {
+    installDesktopBridge()
+
+    render(
+      <LinkifiedText
+        explicitOnly
+        pretty={false}
+        text={'Report  https://paste.rs/abc\nagent.log  https://paste.rs/def\nerrors.log'}
+      />
+    )
+
+    const links = screen.getAllByRole('link')
+    expect(links.map(a => a.getAttribute('href'))).toEqual(['https://paste.rs/abc', 'https://paste.rs/def'])
+    // Bare filename-shaped tokens stay as plain text, not links.
+    expect(screen.queryByText(content => content.includes('agent.log'))).toBeTruthy()
+    expect(links.some(a => (a.textContent ?? '').includes('.log'))).toBe(false)
+  })
+
+  it('without explicitOnly, bare filename tokens are still linkified (default behavior)', () => {
+    installDesktopBridge()
+
+    render(<LinkifiedText pretty={false} text="open agent.log please" />)
+
+    const link = screen.getByRole('link', { name: 'agent.log' })
+    expect(link.getAttribute('href')).toBe('https://agent.log')
+  })
 })

package/agent/apps/desktop/src/lib/external-link.tsx

@@ -12,6 +12,12 @@ const titleSubs = new Map<string, Set<(value: string) => void>>()
 const URL_RE =
   /(?:https?:\/\/|www\.)[^\s<>"'`]+[^\s<>"'`.,;:!?)]|[a-z0-9](?:[a-z0-9-]*\.)+[a-z]{2,}(?:\/[^\s<>"'`.,;:!?)]*)?/gi
 
+// Explicit-scheme / www. URLs only — no bare-domain matching. Used where the
+// surrounding text is full of filename-shaped tokens (e.g. `agent.log`,
+// `errors.log` in a /debug report) that the bare-domain branch of URL_RE would
+// otherwise mistake for domains and linkify.
+const EXPLICIT_URL_RE = /(?:https?:\/\/|www\.)[^\s<>"'`]+[^\s<>"'`.,;:!?)]/gi
+
 const DOMAIN_RE = /^(?:www\.)?[a-z0-9](?:[a-z0-9-]*\.)+[a-z]{2,}(?::\d+)?(?:[/?#][^\s]*)?$/i
 const SKIP_PROTO_RE = /^(?:file|data|mailto|javascript|blob|chrome|about|hermes):/i
 const LOCAL_HOST_RE = /^(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?$/i
@@ -261,13 +267,14 @@ interface LinkifiedTextProps {
   className?: string
   text: string
   pretty?: boolean
+  explicitOnly?: boolean
 }
 
-export function LinkifiedText({ className, pretty = true, text }: LinkifiedTextProps) {
+export function LinkifiedText({ className, explicitOnly = false, pretty = true, text }: LinkifiedTextProps) {
   const nodes: ReactNode[] = []
   let cursor = 0
 
-  for (const match of text.matchAll(URL_RE)) {
+  for (const match of text.matchAll(explicitOnly ? EXPLICIT_URL_RE : URL_RE)) {
     const raw = match[0]
     const url = normalizeExternalUrl(raw)
     const index = match.index ?? 0

package/agent/apps/desktop/src/lib/gateway-events.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+
+import { gatewayEventRequiresSessionId } from './gateway-events'
+
+describe('gateway event routing', () => {
+  it('drops only unscoped subagent events (genuinely background work)', () => {
+    expect(gatewayEventRequiresSessionId('subagent.progress')).toBe(true)
+    expect(gatewayEventRequiresSessionId('subagent.start')).toBe(true)
+  })
+
+  it('attributes unscoped foreground turn events to the active chat', () => {
+    // These must NOT be dropped when unscoped — they are the focused turn's own
+    // output, and dropping them loses the live response until a refetch (#42178).
+    expect(gatewayEventRequiresSessionId('message.delta')).toBe(false)
+    expect(gatewayEventRequiresSessionId('message.complete')).toBe(false)
+    expect(gatewayEventRequiresSessionId('reasoning.delta')).toBe(false)
+    expect(gatewayEventRequiresSessionId('tool.start')).toBe(false)
+    expect(gatewayEventRequiresSessionId('approval.request')).toBe(false)
+  })
+
+  it('allows global events to remain unscoped', () => {
+    expect(gatewayEventRequiresSessionId('gateway.ready')).toBe(false)
+    expect(gatewayEventRequiresSessionId('preview.restart.progress')).toBe(false)
+    expect(gatewayEventRequiresSessionId('session.info')).toBe(false)
+    expect(gatewayEventRequiresSessionId(undefined)).toBe(false)
+  })
+})

package/agent/apps/desktop/src/lib/gateway-events.ts

@@ -11,6 +11,22 @@ function asRecord(payload: unknown): Record<string, unknown> {
   return payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {}
 }
 
+/**
+ * Whether an unscoped event (no `session_id`) must be dropped rather than
+ * attributed to the focused chat.
+ *
+ * Only `subagent.*` qualifies: it describes background/async work that must
+ * never attach to whichever chat happens to be focused. Every other scoped
+ * event — message/reasoning/thinking/tool/status/prompt — is, when unscoped,
+ * the active turn's own output. The gateway always stamps a *background*
+ * session's events with that session's id, so a missing id can only mean "the
+ * focused turn". #42178 dropped those too, which silently swallowed the live
+ * answer; it then reappeared only after a transcript refetch (manual refresh).
+ */
+export function gatewayEventRequiresSessionId(eventType: string | undefined): boolean {
+  return eventType?.startsWith('subagent.') ?? false
+}
+
 export function gatewayEventCompletedFileDiff(event: RpcEventLike): boolean {
   if (event.type !== 'tool.complete') {
     return false

package/agent/apps/desktop/src/lib/gateway-ws-url.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { GatewayReauthRequiredError, isGatewayReauthRequired, resolveGatewayWsUrl } from './gateway-ws-url'
+
+const oauthConn = { authMode: 'oauth' as const, wsUrl: 'ws://host/api/ws?ticket=stale' }
+const tokenConn = { authMode: 'token' as const, wsUrl: 'ws://host/api/ws?token=abc' }
+
+describe('resolveGatewayWsUrl', () => {
+  describe('oauth mode', () => {
+    it('uses the freshly minted URL', async () => {
+      const getGatewayWsUrl = vi.fn().mockResolvedValue('ws://host/api/ws?ticket=fresh')
+      await expect(resolveGatewayWsUrl({ getGatewayWsUrl }, oauthConn)).resolves.toBe('ws://host/api/ws?ticket=fresh')
+      expect(getGatewayWsUrl).toHaveBeenCalledOnce()
+    })
+
+    it('throws a reauth error instead of falling back to the stale cached ticket', async () => {
+      const getGatewayWsUrl = vi.fn().mockRejectedValue(new Error('401 cookie expired'))
+      await expect(resolveGatewayWsUrl({ getGatewayWsUrl }, oauthConn)).rejects.toBeInstanceOf(
+        GatewayReauthRequiredError
+      )
+    })
+
+    it('preserves the underlying mint failure as the cause', async () => {
+      const cause = new Error('401 cookie expired')
+      const getGatewayWsUrl = vi.fn().mockRejectedValue(cause)
+      const error = await resolveGatewayWsUrl({ getGatewayWsUrl }, oauthConn).catch(e => e)
+      expect(error).toBeInstanceOf(GatewayReauthRequiredError)
+      expect((error as GatewayReauthRequiredError).cause).toBe(cause)
+    })
+
+    it('throws a reauth error when the preload cannot mint (no method)', async () => {
+      await expect(resolveGatewayWsUrl({}, oauthConn)).rejects.toBeInstanceOf(GatewayReauthRequiredError)
+    })
+
+    it('never returns the stale cached ticket on failure', async () => {
+      const getGatewayWsUrl = vi.fn().mockRejectedValue(new Error('boom'))
+      const result = await resolveGatewayWsUrl({ getGatewayWsUrl }, oauthConn).catch(() => 'threw')
+      expect(result).toBe('threw')
+      expect(result).not.toBe(oauthConn.wsUrl)
+    })
+  })
+
+  describe('token / local mode', () => {
+    it('uses the minted URL when available', async () => {
+      const getGatewayWsUrl = vi.fn().mockResolvedValue('ws://host/api/ws?token=fresh')
+      await expect(resolveGatewayWsUrl({ getGatewayWsUrl }, tokenConn)).resolves.toBe('ws://host/api/ws?token=fresh')
+    })
+
+    it('falls back to the cached URL when minting fails (token is long-lived)', async () => {
+      const getGatewayWsUrl = vi.fn().mockRejectedValue(new Error('transient'))
+      await expect(resolveGatewayWsUrl({ getGatewayWsUrl }, tokenConn)).resolves.toBe(tokenConn.wsUrl)
+    })
+
+    it('falls back to the cached URL when the preload method is absent', async () => {
+      await expect(resolveGatewayWsUrl({}, tokenConn)).resolves.toBe(tokenConn.wsUrl)
+    })
+
+    it('treats a missing authMode as non-oauth (falls back safely)', async () => {
+      await expect(resolveGatewayWsUrl({}, { wsUrl: tokenConn.wsUrl })).resolves.toBe(tokenConn.wsUrl)
+    })
+  })
+})
+
+describe('isGatewayReauthRequired', () => {
+  it('detects the dedicated error class', () => {
+    expect(isGatewayReauthRequired(new GatewayReauthRequiredError('x'))).toBe(true)
+  })
+
+  it('detects plain objects tagged with needsOauthLogin (from the main process)', () => {
+    expect(isGatewayReauthRequired({ needsOauthLogin: true })).toBe(true)
+  })
+
+  it('rejects generic errors', () => {
+    expect(isGatewayReauthRequired(new Error('connection closed'))).toBe(false)
+    expect(isGatewayReauthRequired(null)).toBe(false)
+    expect(isGatewayReauthRequired('string')).toBe(false)
+  })
+})