fix(native-chat): /clear starts nothing; the new chat's first message starts its agent

src/main/claude/claude-at-rest-commands.ts

@@ -0,0 +1,145 @@
+import { join } from 'node:path'
+import type { AgentSessionRecord } from '../../shared/agent-session-record'
+import type { AgentSessionSlashCommand } from '../../shared/agent-session-wire'
+import { structuredSlashCommands } from '../../shared/structured-agent-session-composer'
+import { discoverSkills } from '../skills/discovery'
+import { scanClaudeCommandFolders } from './claude-command-folder-scan'
+import { supportsClaudeStructuredLocation } from './claude-structured-location-support'
+
+/** How long one scan answers for a workspace and account before the next read scans again. */
+export const CLAUDE_AT_REST_COMMANDS_TTL_MS = 10_000
+/** A scan still unanswered this long no longer holds the next one off, so a hung folder can't
+ *  freeze the menu. At most two run at once, so a folder that stays hung holds no more. */
+const SCAN_OVERDUE_MS = 30_000
+const MAX_SCANS_IN_FLIGHT = 2
+
+export type ClaudeAtRestCommandsDeps = {
+  resolveWorkspacePath: (workspaceId: string) => Promise<string>
+  now?: () => number
+  discover?: typeof discoverSkills
+}
+
+type Entry = {
+  commands?: AgentSessionSlashCommand[]
+  /** When the kept answer, or the last failure, landed. */
+  scannedAt: number
+  lastStartedAt: number
+  inFlight: number
+  /** Numbers each scan, so only an answer newer than the one kept replaces it. */
+  started: number
+  kept: number
+}
+
+/**
+ * The `/` surface of a Claude chat whose Claude is not running, read from the folders Claude reads
+ * its own from on the host that runs it: the account's and the workspace's command folders and
+ * skills, beside the commands the chat's menu always offers. Nothing until the first scan lands;
+ * `onChange` fires when a scan finds something different.
+ */
+export class ClaudeAtRestCommandCatalog {
+  private readonly entries = new Map<string, Entry>()
+  private readonly listeners = new Set<() => void>()
+
+  constructor(private readonly deps: ClaudeAtRestCommandsDeps) {}
+
+  read = (record: AgentSessionRecord): AgentSessionSlashCommand[] | undefined => {
+    // Another host's folders are only readable there, so this host never answers for them.
+    if (record.provider !== 'claude' || !supportsClaudeStructuredLocation(record.location)) {
+      return undefined
+    }
+    const key = JSON.stringify([record.location.workspaceId, record.accountHome.path])
+    let entry = this.entries.get(key)
+    if (!entry) {
+      entry = {
+        scannedAt: Number.NEGATIVE_INFINITY,
+        lastStartedAt: Number.NEGATIVE_INFINITY,
+        inFlight: 0,
+        started: 0,
+        kept: 0
+      }
+      this.entries.set(key, entry)
+    }
+    const now = this.now()
+    const due =
+      entry.inFlight === 0
+        ? now - entry.scannedAt >= CLAUDE_AT_REST_COMMANDS_TTL_MS
+        : entry.inFlight < MAX_SCANS_IN_FLIGHT && now - entry.lastStartedAt >= SCAN_OVERDUE_MS
+    if (due) {
+      this.scanInto(entry, record)
+    }
+    return entry.commands
+  }
+
+  onChange = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  private scanInto(entry: Entry, record: AgentSessionRecord): void {
+    const scan = ++entry.started
+    entry.lastStartedAt = this.now()
+    entry.inFlight += 1
+    const newest = () => {
+      if (scan < entry.kept) {
+        return false
+      }
+      entry.kept = scan
+      entry.scannedAt = this.now()
+      return true
+    }
+    void this.scan(record)
+      .then(
+        (commands) => {
+          if (!newest() || JSON.stringify(commands) === JSON.stringify(entry.commands)) {
+            return
+          }
+          entry.commands = commands
+          for (const listener of this.listeners) {
+            listener()
+          }
+        },
+        (error: unknown) => {
+          // Waits out the window before trying again, but leaves room for an older scan's answer.
+          entry.scannedAt = this.now()
+          console.warn('[claude] reading the at-rest `/` commands failed:', error)
+        }
+      )
+      .finally(() => {
+        entry.inFlight -= 1
+      })
+  }
+
+  private async scan(record: AgentSessionRecord): Promise<AgentSessionSlashCommand[]> {
+    const cwd = await this.deps.resolveWorkspacePath(record.location.workspaceId)
+    const account = record.accountHome.path
+    const [custom, discovered] = await Promise.all([
+      scanClaudeCommandFolders([join(cwd, '.claude', 'commands'), join(account, 'commands')]),
+      (this.deps.discover ?? discoverSkills)({
+        repos: [],
+        cwd,
+        providerRootOverrides: { claude: join(account, 'skills') }
+      })
+    ])
+    // What the menu offers a Claude chat at rest without a list, so reading one loses none of it.
+    const builtIn = structuredSlashCommands(['clear', 'compact'], 'claude').map(
+      (command): AgentSessionSlashCommand => ({
+        name: command.name,
+        kind: 'command',
+        ...(command.description ? { description: command.description } : {})
+      })
+    )
+    const names = new Set(builtIn.map((command) => command.name))
+    const skills = discovered.skills
+      .filter((skill) => skill.providers.includes('claude'))
+      .map((skill): AgentSessionSlashCommand => ({
+        name: skill.name,
+        kind: 'skill',
+        ...(skill.description ? { description: skill.description } : {})
+      }))
+    return [...builtIn, ...custom.filter((command) => !names.has(command.name)), ...skills]
+  }
+
+  private now(): number {
+    return this.deps.now?.() ?? Date.now()
+  }
+}

src/main/claude/claude-command-folder-scan.ts

@@ -0,0 +1,88 @@
+import type { Dirent } from 'node:fs'
+import { opendir, readFile } from 'node:fs/promises'
+import { join, relative, sep } from 'node:path'
+import type { AgentSessionSlashCommand } from '../../shared/agent-session-wire'
+import { summarizeSkillMarkdown } from '../../shared/skill-metadata'
+
+const MARKDOWN_EXTENSION = '.md'
+const MAX_SCAN_DEPTH = 24
+const MAX_SCAN_ENTRIES = 1_000
+const MAX_COMMAND_FILE_BYTES = 256 * 1024
+
+type ScanBudget = { remainingEntries: number }
+
+/** A folder that cannot be read holds no commands we can offer, so it is skipped, not an error. */
+async function readEntries(path: string, budget: ScanBudget): Promise<Dirent[]> {
+  try {
+    const entries: Dirent[] = []
+    for await (const entry of await opendir(path)) {
+      if (budget.remainingEntries === 0) {
+        break
+      }
+      budget.remainingEntries -= 1
+      entries.push(entry)
+    }
+    return entries.sort((left, right) => left.name.localeCompare(right.name))
+  } catch {
+    return []
+  }
+}
+
+async function walkMarkdown(
+  path: string,
+  depth: number,
+  budget: ScanBudget,
+  found: string[]
+): Promise<void> {
+  if (depth > MAX_SCAN_DEPTH || budget.remainingEntries === 0) {
+    return
+  }
+  for (const entry of await readEntries(path, budget)) {
+    // Links are not followed: a command folder is the user's own files, not a way out of it.
+    if (entry.isSymbolicLink()) {
+      continue
+    }
+    const entryPath = join(path, entry.name)
+    if (entry.isDirectory()) {
+      await walkMarkdown(entryPath, depth + 1, budget, found)
+    } else if (entry.isFile() && entry.name.endsWith(MARKDOWN_EXTENSION)) {
+      found.push(entryPath)
+    }
+  }
+}
+
+async function describe(filePath: string): Promise<string | undefined> {
+  try {
+    const markdown = await readFile(filePath, 'utf8')
+    return (
+      summarizeSkillMarkdown(markdown.slice(0, MAX_COMMAND_FILE_BYTES)).description ?? undefined
+    )
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Claude's custom commands in `roots`: every `*.md` below each folder, named by its path from
+ * the folder with `:` between segments (`frontend/test.md` is `/frontend:test`). The first root
+ * to name a command wins, so list the closest folder first.
+ */
+export async function scanClaudeCommandFolders(
+  roots: readonly string[]
+): Promise<AgentSessionSlashCommand[]> {
+  const budget = { remainingEntries: MAX_SCAN_ENTRIES }
+  const commands = new Map<string, AgentSessionSlashCommand>()
+  for (const root of roots) {
+    const files: string[] = []
+    await walkMarkdown(root, 0, budget, files)
+    for (const file of files) {
+      const name = relative(root, file).slice(0, -MARKDOWN_EXTENSION.length).split(sep).join(':')
+      if (commands.has(name)) {
+        continue
+      }
+      const description = await describe(file)
+      commands.set(name, { name, kind: 'command', ...(description ? { description } : {}) })
+    }
+  }
+  return [...commands.values()]
+}

src/main/claude/claude-structured-session-adapter.ts

@@ -63,6 +63,7 @@ export class ClaudeStructuredSessionAdapter implements StructuredAgentSessionAda
   private readonly exitLifecycle: ClaudeExitLifecycle
 
   constructor(private readonly deps: ClaudeStructuredSessionAdapterDeps) {
+    this.atRestCommands = deps.atRestCommands
     this.exitLifecycle = {
       sessions: this.sessions,
       exits: this.exits,
@@ -232,6 +233,7 @@ export class ClaudeStructuredSessionAdapter implements StructuredAgentSessionAda
     this.sessions.has(sessionId) ? { supportsTaskStop: true, supportsStopAll: true } : undefined
   readCommands: NonNullable<StructuredAgentSessionAdapter['readCommands']> = (sessionId) =>
     this.sessions.get(sessionId)?.commands.commands
+  readonly atRestCommands: ClaudeStructuredSessionAdapterDeps['atRestCommands']
   holdsDispatch = (sessionId: string): boolean => {
     const session = this.sessions.get(sessionId)
     return session ? claudeHoldsDispatch(session) : false

src/main/claude/claude-structured-session-state.ts

@@ -27,6 +27,7 @@ import type { AgentChildWorkEvidence } from '../../shared/agent-status-child-wor
 import type { ClaudeBackgroundTaskTracker } from './claude-background-task-tracker'
 import type { ClaudeChildWorkDecoder } from './claude-child-work-decoder'
 import type { ClaudeSlashCommandCatalog } from './claude-slash-command-catalog'
+import type { ClaudeAtRestCommandCatalog } from './claude-at-rest-commands'
 import type { ClaudeSessionStartup } from './claude-structured-session-startup-state'
 
 export type ClaudeAuthDiagnostic = {
@@ -93,6 +94,8 @@ export type ClaudeLateDispatchOutcome =
   | { clientMessageId: string; state: 'unknown'; reason: string }
 
 export type ClaudeStructuredSessionAdapterDeps = {
+  /** The `/` surface of a chat whose Claude is not running. */
+  atRestCommands?: ClaudeAtRestCommandCatalog
   resolveLaunch: (input: {
     identity: AgentSessionJournalIdentity
   }) => Promise<ClaudeStructuredLaunch>

src/main/native-chat/agent-session-wire/structured-agent-session-adapter-router.ts

@@ -1,4 +1,5 @@
 import type { SubmissionRejectionFact } from '../../../shared/agent-session-failure'
+import type { StructuredAgentSessionAtRestCommands } from './structured-agent-session-at-rest-commands'
 import type { AgentSessionJournalIdentity } from '../../../shared/agent-session-journal-types'
 import type {
   AgentSessionAccountHome,
@@ -121,6 +122,16 @@ export class StructuredAgentSessionAdapterRouter implements StructuredAgentSessi
   readCommands: NonNullable<StructuredAgentSessionAdapter['readCommands']> = (sessionId) =>
     this.liveOwnerOrNull(sessionId)?.readCommands?.(sessionId)
 
+  atRestCommands: StructuredAgentSessionAtRestCommands = {
+    read: (record) => this.adapters[record.provider].atRestCommands?.read(record),
+    onChange: (listener) => {
+      const stops = Object.values(this.adapters).flatMap((adapter) =>
+        adapter.atRestCommands ? [adapter.atRestCommands.onChange(listener)] : []
+      )
+      return () => stops.forEach((stop) => stop())
+    }
+  }
+
   answerPrompt: StructuredAgentSessionAdapter['answerPrompt'] = (input) =>
     this.owner(input.sessionId).answerPrompt(input)
 

src/main/native-chat/agent-session-wire/structured-agent-session-adapter.ts

@@ -25,6 +25,7 @@ import type {
   AgentSessionExecutionLocation,
   AgentSessionProcessIdentity
 } from '../../../shared/agent-session-record'
+import type { StructuredAgentSessionAtRestCommands } from './structured-agent-session-at-rest-commands'
 import type {
   AgentSessionOptionsResult,
   AgentSessionSlashCommand,
@@ -347,6 +348,8 @@ export type StructuredAgentSessionAdapter = {
   /** The `/` surface the running provider reports for itself. Undefined when the
    *  provider never reports one, which is what keeps the client on its catalog. */
   readCommands?(sessionId: string): AgentSessionSlashCommand[] | undefined
+  /** The `/` surface of a chat whose agent is not running; absent when the provider has none. */
+  atRestCommands?: StructuredAgentSessionAtRestCommands
   /** Claims the live callback, builds the provider reply, commits the journal CAS while that claim is
    *  held, then answers it. A reply that cannot be built throws `AgentSessionPromptAnswerRejectedError`
    *  before the commit. A prompt cancel claims the same callback, so only one operation can commit. */