@xelauvas/xela-cli 0.3.1 → 0.4.0

package/src/services/skillSearch/prefetch.ts

@@ -0,0 +1,125 @@
+import type { Command } from '../../commands.js'
+import type { ToolUseContext } from '../../Tool.js'
+import type { Message } from '../../types/message.js'
+import type { Attachment } from '../../utils/attachments.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { isSkillSearchEnabled } from './featureCheck.js'
+import { searchSkills } from './localSearch.js'
+import type { DiscoverySignal } from './signals.js'
+
+export type PendingSkillPrefetch = {
+  promise: Promise<Attachment[]>
+  signal: DiscoverySignal
+  startedAt: number
+}
+
+// Skills already surfaced in this process, per agent, so suggestions are not repeated
+const surfaced = new Map<string, Set<string>>()
+
+function surfacedFor(context: ToolUseContext): Set<string> {
+  const key = (context as { agentId?: string }).agentId ?? 'main'
+  let set = surfaced.get(key)
+  if (!set) {
+    set = new Set()
+    surfaced.set(key, set)
+  }
+  return set
+}
+
+function textOf(message: Message | undefined): string {
+  if (!message) return ''
+  const m = message as { type: string; message?: { content?: unknown } }
+  if (m.type !== 'user' && m.type !== 'assistant') return ''
+  const content = m.message?.content
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return (content as Array<{ type: string; text?: string; name?: string }>)
+    .map(b => (b.type === 'text' ? b.text ?? '' : b.type === 'tool_use' ? b.name ?? '' : ''))
+    .join(' ')
+}
+
+/** Skills that the listing already shows (bundled + MCP) are never "discovered". */
+function discoverable(cmd: { loadedFrom?: string; source?: string }): boolean {
+  const from = cmd.loadedFrom ?? cmd.source
+  return from !== 'bundled' && from !== 'mcp' && from !== 'builtin'
+}
+
+async function discover(
+  query: string,
+  signal: DiscoverySignal,
+  context: ToolUseContext,
+): Promise<Attachment[]> {
+  if (!isSkillSearchEnabled()) return []
+  const text = query.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+  if (text.length < 12) return []
+  // The session's command list travels on the tool-use context; loading it
+  // here would drag the whole command graph through the CJS require shim.
+  const all = (context.options as { commands?: Command[] } | undefined)?.commands ?? []
+  const commands = all.filter(discoverable)
+  if (commands.length === 0) {
+    logForDebugging('[skill-search] no commands on context; skipping discovery')
+    return []
+  }
+  logForDebugging(`[skill-search] ${signal}: ${commands.length} candidate skills, query "${text.slice(0, 80)}"`)
+  const already = surfacedFor(context)
+  const hits = searchSkills(text, commands, { limit: 4, exclude: already })
+  if (hits.length === 0) return []
+  for (const h of hits) {
+    already.add(h.name)
+    context.discoveredSkillNames?.add(h.name)
+  }
+  if (!context.discoveredSkillNames) {
+    ;(context as { discoveredSkillNames?: Set<string> }).discoveredSkillNames = new Set(hits.map(h => h.name))
+  }
+  logForDebugging(`[skill-search] ${signal}: ${hits.map(h => `${h.name}(${h.score.toFixed(1)})`).join(', ')}`)
+  return [
+    {
+      type: 'skill_discovery',
+      skills: hits.map(h => ({ name: h.name, description: h.description })),
+      signal,
+      source: 'native',
+    } as Attachment,
+  ]
+}
+
+/** Turn 0: the user's own words are the signal. Blocking, but the index is in-memory. */
+export async function getTurnZeroSkillDiscovery(
+  input: string,
+  _messages: Message[],
+  context: ToolUseContext,
+): Promise<Attachment[]> {
+  return discover(input, 'user_input', context)
+}
+
+/**
+ * Between turns: what the assistant just said and what the user asked
+ * before are the signal. Runs while the main turn is in flight; the result
+ * is collected by collectSkillDiscoveryPrefetch before the next model call.
+ */
+export function startSkillDiscoveryPrefetch(
+  signal: DiscoverySignal | null,
+  messages: Message[],
+  context: ToolUseContext,
+): PendingSkillPrefetch | null {
+  if (!isSkillSearchEnabled()) return null
+  const lastAssistant = [...messages].reverse().find(m => m.type === 'assistant')
+  if (!lastAssistant) return null
+  const lastUser = [...messages].reverse().find(m => m.type === 'user' && !(m as { isMeta?: boolean }).isMeta)
+  const query = `${textOf(lastUser)} ${textOf(lastAssistant)}`.slice(0, 4000)
+  const effective: DiscoverySignal = signal ?? 'assistant_turn'
+  return {
+    promise: discover(query, effective, context).catch(() => []),
+    signal: effective,
+    startedAt: Date.now(),
+  }
+}
+
+export async function collectSkillDiscoveryPrefetch(
+  pending: PendingSkillPrefetch,
+): Promise<Attachment[]> {
+  return pending.promise
+}
+
+export function resetSkillDiscoveryState(): void {
+  surfaced.clear()
+}

package/src/services/skillSearch/remoteSkillLoader.ts

@@ -0,0 +1,9 @@
+import type { RemoteSkillMeta } from './remoteSkillState.js'
+
+export type RemoteSkillLoadResult = { content: string; fromCache: boolean }
+
+export async function loadRemoteSkill(meta: RemoteSkillMeta): Promise<RemoteSkillLoadResult> {
+  throw new Error(
+    `Remote skills are not available in this build (requested ${meta.slug}). Install the skill locally under .claude/skills or the config dir.`,
+  )
+}

package/src/services/skillSearch/remoteSkillState.ts

@@ -0,0 +1,21 @@
+/**
+ * Remote ("canonical") skills live on Anthropic infrastructure and are not
+ * reachable from a local build. The API is kept so SkillTool compiles and
+ * behaves: nothing is ever discovered, so the prefixed names are rejected
+ * with a clear message instead of a crash.
+ */
+export type RemoteSkillMeta = { slug: string; url: string; description?: string }
+
+const CANONICAL_PREFIX = '_canonical_'
+
+export function stripCanonicalPrefix(name: string): string | null {
+  return name.startsWith(CANONICAL_PREFIX) ? name.slice(CANONICAL_PREFIX.length) : null
+}
+
+export function getDiscoveredRemoteSkill(_slug: string): RemoteSkillMeta | undefined {
+  return undefined
+}
+
+export function registerDiscoveredRemoteSkill(_meta: RemoteSkillMeta): void {}
+
+export function clearDiscoveredRemoteSkills(): void {}

package/src/services/skillSearch/signals.ts

@@ -0,0 +1,7 @@
+/** What triggered a skill discovery pass. */
+export type DiscoverySignal =
+  | 'user_input'
+  | 'assistant_turn'
+  | 'subagent_spawn'
+  | 'tool_call'
+  | 'explicit'

package/src/services/skillSearch/telemetry.ts

@@ -0,0 +1,9 @@
+import { logForDebugging } from '../../utils/debug.js'
+
+export function logRemoteSkillLoaded(slug: string, details?: Record<string, unknown>): void {
+  logForDebugging(`[skill-search] remote skill loaded ${slug} ${details ? JSON.stringify(details) : ''}`)
+}
+
+export function logSkillDiscovery(details: Record<string, unknown>): void {
+  logForDebugging(`[skill-search] ${JSON.stringify(details)}`)
+}

package/src/setup.ts

@@ -1,5 +1,6 @@
 /* eslint-disable custom-rules/no-process-exit */
 
+import { logForDebugging } from './utils/debug.js'
 import { feature } from 'bun:bundle'
 import chalk from 'chalk'
 import {
@@ -93,11 +94,15 @@ export async function setup(
     // and $CLAUDE_CODE_MESSAGING_SOCKET is exported before any hook
     // (SessionStart in particular) can spawn and snapshot process.env.
     if (feature('UDS_INBOX')) {
-      const m = await import('./utils/udsMessaging.js')
-      await m.startUdsMessaging(
-        messagingSocketPath ?? m.getDefaultUdsSocketPath(),
-        { isExplicit: messagingSocketPath !== undefined },
-      )
+      try {
+        const m = await import('./utils/udsMessaging.js')
+        await m.startUdsMessaging(
+          messagingSocketPath ?? m.getDefaultUdsSocketPath(),
+          { isExplicit: messagingSocketPath !== undefined },
+        )
+      } catch (e) {
+        logForDebugging(`[uds] messaging server not started: ${String(e)}`)
+      }
     }
   }
 

package/src/skills/bundled/dream.ts

@@ -0,0 +1,31 @@
+import { getAutoMemPath, isAutoMemoryEnabled } from '../../memdir/paths.js'
+import { buildConsolidationPrompt } from '../../services/autoDream/consolidationPrompt.js'
+import { getOriginalCwd } from '../../bootstrap/state.js'
+import { getProjectDir } from '../../utils/sessionStorage.js'
+import { registerBundledSkill } from '../bundledSkills.js'
+
+/**
+ * /dream: a manual memory-consolidation pass. Auto-dream runs the same
+ * prompt in a forked, read-only agent between sessions; this runs it in the
+ * main loop with normal permissions so the user can watch and steer.
+ */
+export function registerDreamSkill(): void {
+  registerBundledSkill({
+    name: 'dream',
+    description:
+      'Consolidate recent memory: distill daily logs and session learnings into well-organized memory files and refresh the index',
+    whenToUse:
+      'When the user asks to consolidate, clean up, reorganize or "dream" over memory, or when memory files have grown stale or duplicated.',
+    argumentHint: '[focus or extra instructions]',
+    userInvocable: true,
+    isEnabled: () => isAutoMemoryEnabled(),
+    async getPromptForCommand(args) {
+      const memoryRoot = getAutoMemPath()
+      const transcriptDir = getProjectDir(getOriginalCwd())
+      const extra = args?.trim()
+        ? `\n\nFocus for this pass: ${args.trim()}`
+        : '\n\nThis is a manual pass started by the user; summarize what you changed when you are done.'
+      return [{ type: 'text', text: buildConsolidationPrompt(memoryRoot, transcriptDir, extra) }]
+    },
+  })
+}

package/src/skills/bundled/hunter.ts

@@ -0,0 +1,45 @@
+import { registerBundledSkill } from '../bundledSkills.js'
+
+const HUNTER_PROMPT = `# Bug hunt {{scope}}
+
+You are hunting for real defects in a set of changes and producing a review artifact the team can act on. Findings must be verified against the code, not guessed from the diff.
+
+## Step 1: Establish the scope
+- If a scope was given above, use it (a PR number via \`gh pr diff\`, a commit range, a branch, or a list of files).
+- Otherwise use the working tree: \`git diff\` plus \`git diff --cached\`; if both are empty, use \`git diff origin/HEAD...HEAD\` or the last commit.
+- List the changed files and skim the whole diff once before digging in.
+
+## Step 2: Hunt
+For each hunk, ask what could go wrong at runtime and check it by reading the surrounding code (callers, callees, types, tests), not only the diff:
+- correctness: wrong conditions, off-by-one, null/undefined paths, error handling that swallows failures, async ordering, resource leaks
+- contract breaks: changed signatures or return shapes with callers not updated, serialization or schema mismatches
+- security: injection, path traversal, unsafe shell or SQL construction, secrets in logs
+- concurrency and state: races, shared mutable state, missing cleanup
+- tests: behaviour changed without a test, tests that cannot fail
+Confirm each candidate with a concrete failure scenario (inputs or state, then the wrong outcome). Drop anything you cannot confirm or that is a style preference.
+
+## Step 3: Write the artifact
+Write a Markdown report to \`.claude/reviews/<YYYY-MM-DD>-hunter-<short-scope>.md\` (create the directory if needed) with:
+1. Scope and how it was obtained
+2. Findings, most severe first. For each: title, file:line, severity (blocker / high / medium / low), the failure scenario, and a suggested fix
+3. Things checked and found fine (one line each), so nobody re-reviews them
+4. Open questions that need the author
+
+## Step 4: Report
+Tell the user the path of the artifact and summarize the findings in a short list (one line per finding with file:line). If there are no confirmed findings, say so plainly and name what you checked.`
+
+export function registerHunterSkill(): void {
+  registerBundledSkill({
+    name: 'hunter',
+    description:
+      'Hunts for verified bugs in a diff, PR or branch and writes a review artifact (Markdown report with findings, severities and fixes)',
+    whenToUse:
+      'When the user wants a thorough bug-focused review of changes with a written report, or asks to "hunt for bugs", "find what is wrong with this PR", or produce a review artifact.',
+    argumentHint: '[PR number | commit range | branch | files]',
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      const scope = args?.trim() ? `\n\nScope requested: ${args.trim()}` : ''
+      return [{ type: 'text', text: HUNTER_PROMPT.replace('{{scope}}', scope) }]
+    },
+  })
+}

package/src/skills/bundled/index.ts

@@ -11,6 +11,14 @@ import { registerSkillifySkill } from './skillify.js'
 import { registerStuckSkill } from './stuck.js'
 import { registerUpdateConfigSkill } from './updateConfig.js'
 import { registerVerifySkill } from './verify.js'
+// Feature-gated skills: imported statically (not via require) so they register
+// in the same bundled-skill registry instance as everything else.
+import { registerClaudeApiSkill } from './claudeApi.js'
+import { registerDreamSkill } from './dream.js'
+import { registerHunterSkill } from './hunter.js'
+import { registerLoopSkill } from './loop.js'
+import { registerRunSkillGeneratorSkill } from './runSkillGenerator.js'
+import { registerScheduleRemoteAgentsSkill } from './scheduleRemoteAgents.js'
 
 /**
  * Initialize all bundled skills.
@@ -33,47 +41,26 @@ export function initBundledSkills(): void {
   registerBatchSkill()
   registerStuckSkill()
   if (feature('KAIROS') || feature('KAIROS_DREAM')) {
-    /* eslint-disable @typescript-eslint/no-require-imports */
-    const { registerDreamSkill } = require('./dream.js')
-    /* eslint-enable @typescript-eslint/no-require-imports */
     registerDreamSkill()
   }
   if (feature('REVIEW_ARTIFACT')) {
-    /* eslint-disable @typescript-eslint/no-require-imports */
-    const { registerHunterSkill } = require('./hunter.js')
-    /* eslint-enable @typescript-eslint/no-require-imports */
     registerHunterSkill()
   }
   if (feature('AGENT_TRIGGERS')) {
-    /* eslint-disable @typescript-eslint/no-require-imports */
-    const { registerLoopSkill } = require('./loop.js')
-    /* eslint-enable @typescript-eslint/no-require-imports */
-    // /loop's isEnabled delegates to isKairosCronEnabled() — same lazy
-    // per-invocation pattern as the cron tools. Registered unconditionally;
-    // the skill's own isEnabled callback decides visibility.
+    // /loop's isEnabled delegates to isKairosCronEnabled(); registered
+    // unconditionally, the skill's own isEnabled decides visibility.
     registerLoopSkill()
   }
   if (feature('AGENT_TRIGGERS_REMOTE')) {
-    /* eslint-disable @typescript-eslint/no-require-imports */
-    const {
-      registerScheduleRemoteAgentsSkill,
-    } = require('./scheduleRemoteAgents.js')
-    /* eslint-enable @typescript-eslint/no-require-imports */
     registerScheduleRemoteAgentsSkill()
   }
   if (feature('BUILDING_CLAUDE_APPS')) {
-    /* eslint-disable @typescript-eslint/no-require-imports */
-    const { registerClaudeApiSkill } = require('./claudeApi.js')
-    /* eslint-enable @typescript-eslint/no-require-imports */
     registerClaudeApiSkill()
   }
   if (shouldAutoEnableClaudeInChrome()) {
     registerClaudeInChromeSkill()
   }
   if (feature('RUN_SKILL_GENERATOR')) {
-    /* eslint-disable @typescript-eslint/no-require-imports */
-    const { registerRunSkillGeneratorSkill } = require('./runSkillGenerator.js')
-    /* eslint-enable @typescript-eslint/no-require-imports */
     registerRunSkillGeneratorSkill()
   }
 }

package/src/skills/bundled/runSkillGenerator.ts

@@ -0,0 +1,61 @@
+import { getClaudeConfigHomeDir } from '../../utils/envUtils.js'
+import { registerBundledSkill } from '../bundledSkills.js'
+
+const PROMPT = `# Skill generator {{request}}
+
+You are creating a new reusable skill: a SKILL.md file that teaches a future session how to do one kind of task well.
+
+## Step 1: Pin down the skill
+From the request above (ask one short question if it is genuinely ambiguous):
+- a kebab-case name (3 words max), e.g. \`release-notes\`
+- a one-sentence description starting with "Use when ..." that says when the skill applies and what it produces
+- the inputs it needs (arguments, files, environment) and the tools it should be allowed to use
+
+## Step 2: Research before writing
+Look at how the task is actually done in this repository or environment: existing scripts, conventions, commands that work, pitfalls visible in git history or docs. A skill that repeats generic advice is useless; capture the specific commands, paths and checks.
+
+## Step 3: Write the skill
+Create \`{{skillsDir}}/<name>/SKILL.md\` with this shape:
+
+\`\`\`markdown
+---
+name: <name>
+description: Use when <situation> — <what it does / produces>
+argument-hint: <what to pass, if anything>
+allowed-tools: <comma-separated tool names, only if it should be restricted>
+---
+
+# <Title>
+
+<One paragraph: purpose and when to use it.>
+
+## Inputs
+## Steps
+<Numbered, concrete, with the exact commands and files. Include verification at the end of each major step.>
+## Pitfalls
+## Done when
+<Observable completion criteria.>
+\`\`\`
+
+Keep it under about 150 lines; move long reference material into sibling files in the same directory and link them by relative path.
+
+## Step 4: Verify
+Re-read the file as if you were a new session with no context. Fix anything that assumes knowledge the skill does not provide. Then tell the user the path, the name to invoke it with (\`/<name>\`), and a one-line summary.`
+
+export function registerRunSkillGeneratorSkill(): void {
+  registerBundledSkill({
+    name: 'run-skill-generator',
+    aliases: ['skill-generator', 'generate-skill'],
+    description:
+      'Generates a new reusable skill (SKILL.md) for a task you describe, grounded in how the task is done in this environment',
+    whenToUse:
+      'When the user asks to create, generate or scaffold a new skill or slash command for a recurring task.',
+    argumentHint: '<what the skill should do>',
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      const request = args?.trim() ? `\n\nRequest: ${args.trim()}` : ''
+      const skillsDir = `${getClaudeConfigHomeDir()}/skills`
+      return [{ type: 'text', text: PROMPT.replace('{{request}}', request).replace('{{skillsDir}}', skillsDir) }]
+    },
+  })
+}

package/src/skills/mcpSkills.ts

@@ -0,0 +1,101 @@
+import type { Command } from '../commands.js'
+import type { MCPServerConnection } from '../services/mcp/types.js'
+import { logForDebugging } from '../utils/debug.js'
+import { memoizeWithLRU } from '../utils/memoize.js'
+import { parseYaml } from '../utils/yaml.js'
+
+/**
+ * MCP skills: an MCP server can publish skills as resources. Any resource
+ * whose URI uses the `skill://` scheme, or whose URI/name ends in SKILL.md,
+ * is read, its frontmatter parsed, and exposed as a prompt command named
+ * `mcp__<server>__<skill>` next to the server's prompts.
+ */
+
+type Resource = { uri: string; name?: string; description?: string; mimeType?: string }
+
+function isSkillResource(r: Resource): boolean {
+  const uri = r.uri || ''
+  return uri.startsWith('skill://') || /SKILL\.md$/i.test(uri) || /SKILL\.md$/i.test(r.name || '')
+}
+
+function splitFrontmatter(raw: string): { meta: Record<string, unknown>; body: string } {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
+  if (!m) return { meta: {}, body: raw }
+  let meta: Record<string, unknown> = {}
+  try {
+    const parsed = parseYaml(m[1]!)
+    if (parsed && typeof parsed === 'object') meta = parsed as Record<string, unknown>
+  } catch {
+    // keep going with the body only
+  }
+  return { meta, body: raw.slice(m[0].length) }
+}
+
+function normalizeName(s: string): string {
+  return s.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+function skillNameFromResource(r: Resource, meta: Record<string, unknown>): string {
+  if (typeof meta.name === 'string' && meta.name.trim()) return normalizeName(meta.name.trim())
+  const uri = r.uri.replace(/^skill:\/\//, '')
+  const parts = uri.split('/').filter(Boolean)
+  const last = parts[parts.length - 1] || ''
+  const base = /SKILL\.md$/i.test(last) ? parts[parts.length - 2] || 'skill' : last
+  return normalizeName(base)
+}
+
+export const fetchMcpSkillsForClient = memoizeWithLRU(
+  async (client: MCPServerConnection): Promise<Command[]> => {
+    if (client.type !== 'connected') return []
+    if (!client.capabilities?.resources) return []
+    try {
+      const listed = (await client.client.listResources()) as { resources?: Resource[] }
+      const skills = (listed.resources || []).filter(isSkillResource)
+      if (skills.length === 0) return []
+      const commands: Command[] = []
+      for (const r of skills) {
+        try {
+          const read = (await client.client.readResource({ uri: r.uri })) as {
+            contents?: Array<{ text?: string; blob?: string }>
+          }
+          const text = (read.contents || []).map(c => c.text || '').join('\n').trim()
+          if (!text) continue
+          const { meta, body } = splitFrontmatter(text)
+          const skillName = skillNameFromResource(r, meta)
+          const description =
+            (typeof meta.description === 'string' && meta.description) || r.description || `Skill from ${client.name}`
+          commands.push({
+            type: 'prompt',
+            name: `mcp__${normalizeName(client.name)}__${skillName}`,
+            description,
+            hasUserSpecifiedDescription: true,
+            contentLength: body.length,
+            isEnabled: () => true,
+            isHidden: false,
+            isMcp: true,
+            progressMessage: 'running',
+            userFacingName() {
+              return `${client.name}:${skillName} (MCP skill)`
+            },
+            argNames: [],
+            source: 'mcp',
+            whenToUse: typeof meta['when-to-use'] === 'string' ? (meta['when-to-use'] as string) : undefined,
+            async getPromptForCommand(args: string) {
+              const prompt = args?.trim() ? `${body}\n\n## Arguments\n\n${args.trim()}` : body
+              return [{ type: 'text', text: prompt }]
+            },
+          } as unknown as Command)
+        } catch (e) {
+          logForDebugging(`[mcpSkills] ${client.name}: cannot read ${r.uri}: ${String(e)}`)
+        }
+      }
+      logForDebugging(`[mcpSkills] ${client.name}: ${commands.length} skill(s)`)
+      return commands
+    } catch (e) {
+      logForDebugging(`[mcpSkills] ${client.name}: resources/list failed: ${String(e)}`)
+      return []
+    }
+  },
+  (client: MCPServerConnection) => client.name,
+  50,
+)