@swarmclawai/swarmclaw 0.7.7 → 0.8.0

package/src/lib/server/skill-discovery.ts

@@ -0,0 +1,128 @@
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { DATA_DIR } from './data-dir'
+import { normalizeSkillPayload, type NormalizedSkill } from './skills-normalize'
+
+export interface DiscoveredSkill extends NormalizedSkill {
+  /** Which layer this skill was found in. */
+  source: 'bundled' | 'workspace' | 'project'
+  /** Absolute path to the SKILL.md file. */
+  sourcePath: string
+}
+
+interface DiscoveryCache {
+  skills: DiscoveredSkill[]
+  ids: string[]
+  timestamp: number
+  cacheKey: string
+}
+
+const CACHE_TTL_MS = 5_000
+
+let cache: DiscoveryCache | null = null
+
+function buildCacheKey(cwd?: string): string {
+  return `${cwd || ''}`
+}
+
+function scanLayer(
+  dir: string,
+  source: DiscoveredSkill['source'],
+): DiscoveredSkill[] {
+  const results: DiscoveredSkill[] = []
+  let entries: string[]
+  try {
+    entries = fs.readdirSync(dir)
+  } catch {
+    return results
+  }
+
+  for (const entry of entries) {
+    const skillDir = path.join(dir, entry)
+    let stat: fs.Stats
+    try {
+      stat = fs.statSync(skillDir)
+    } catch {
+      continue
+    }
+    if (!stat.isDirectory()) continue
+
+    const skillFile = path.join(skillDir, 'SKILL.md')
+    let content: string
+    try {
+      content = fs.readFileSync(skillFile, 'utf-8')
+    } catch {
+      continue
+    }
+
+    const normalized = normalizeSkillPayload({
+      content,
+      filename: `${entry}.md`,
+    })
+
+    results.push({
+      ...normalized,
+      source,
+      sourcePath: skillFile,
+    })
+  }
+
+  return results
+}
+
+/**
+ * Discover skills from three layers:
+ *   1. Bundled: `data/skills/` (shipped with the app)
+ *   2. Workspace: `~/.swarmclaw/skills/` (user-installed)
+ *   3. Project: `<cwd>/skills/` (project-local)
+ *
+ * Results are cached with a 5-second TTL. Later layers override
+ * earlier ones when names collide (project > workspace > bundled).
+ */
+export function discoverSkills(opts?: { cwd?: string }): DiscoveredSkill[] {
+  const cwd = opts?.cwd
+  const cacheKey = buildCacheKey(cwd)
+  const now = Date.now()
+
+  if (cache && cache.cacheKey === cacheKey && now - cache.timestamp < CACHE_TTL_MS) {
+    return cache.skills
+  }
+
+  // Layer 1: Bundled skills
+  const bundledDir = path.join(DATA_DIR, 'skills')
+  const bundled = scanLayer(bundledDir, 'bundled')
+
+  // Layer 2: Workspace skills (~/.swarmclaw/skills/)
+  const workspaceDir = path.join(os.homedir(), '.swarmclaw', 'skills')
+  const workspace = scanLayer(workspaceDir, 'workspace')
+
+  // Layer 3: Project-local skills (<cwd>/skills/)
+  let project: DiscoveredSkill[] = []
+  if (cwd) {
+    const projectDir = path.join(cwd, 'skills')
+    project = scanLayer(projectDir, 'project')
+  }
+
+  // Deduplicate: later layers win on name collision
+  const byName = new Map<string, DiscoveredSkill>()
+  for (const skill of [...bundled, ...workspace, ...project]) {
+    byName.set(skill.name.toLowerCase(), skill)
+  }
+  const skills = Array.from(byName.values())
+  const ids = skills.map((s) => s.name)
+
+  cache = { skills, ids, timestamp: now, cacheKey }
+  return skills
+}
+
+/**
+ * Return the names of all currently discovered skills (uses cache if warm).
+ */
+export function getDiscoveredSkillIds(): string[] {
+  if (cache && Date.now() - cache.timestamp < CACHE_TTL_MS) {
+    return cache.ids
+  }
+  // Cold call without cwd — returns bundled + workspace only
+  return discoverSkills().map((s) => s.name)
+}

package/src/lib/server/skill-eligibility.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { evaluateRequirements, clearBinaryCache } from './skill-eligibility'
+import type { SkillRequirements } from '@/types'
+
+describe('evaluateRequirements', () => {
+  beforeEach(() => {
+    clearBinaryCache()
+  })
+
+  it('returns eligible when no requirements', () => {
+    const result = evaluateRequirements({})
+    assert.equal(result.eligible, true)
+    assert.equal(result.reasons.length, 0)
+  })
+
+  it('passes when required binary exists (node)', () => {
+    const result = evaluateRequirements({ bins: ['node'] })
+    assert.equal(result.eligible, true)
+    assert.equal(result.missingBins.length, 0)
+  })
+
+  it('fails when required binary is missing', () => {
+    const result = evaluateRequirements({ bins: ['nonexistent_binary_xyz_123'] })
+    assert.equal(result.eligible, false)
+    assert.deepEqual(result.missingBins, ['nonexistent_binary_xyz_123'])
+    assert.ok(result.reasons[0].includes('Missing binaries'))
+  })
+
+  it('handles anyBins groups — passes when at least one exists', () => {
+    const result = evaluateRequirements({
+      anyBins: [['node', 'nonexistent_abc']],
+    })
+    assert.equal(result.eligible, true)
+    assert.equal(result.missingAnyBins.length, 0)
+  })
+
+  it('handles anyBins groups — fails when none exist', () => {
+    const result = evaluateRequirements({
+      anyBins: [['nonexistent_a', 'nonexistent_b']],
+    })
+    assert.equal(result.eligible, false)
+    assert.equal(result.missingAnyBins.length, 1)
+  })
+
+  it('checks environment variables', () => {
+    const result = evaluateRequirements({ env: ['VERY_UNLIKELY_ENV_VAR_XYZ'] })
+    assert.equal(result.eligible, false)
+    assert.deepEqual(result.missingEnv, ['VERY_UNLIKELY_ENV_VAR_XYZ'])
+  })
+
+  it('passes env check when env var is set', () => {
+    // PATH is always set
+    const result = evaluateRequirements({ env: ['PATH'] })
+    assert.equal(result.eligible, true)
+    assert.equal(result.missingEnv.length, 0)
+  })
+
+  it('checks OS compatibility — passes on current platform', () => {
+    const result = evaluateRequirements({ os: [process.platform] })
+    assert.equal(result.eligible, true)
+    assert.equal(result.unsupportedOs, false)
+  })
+
+  it('checks OS compatibility — fails on wrong platform', () => {
+    const result = evaluateRequirements({ os: ['nonexistent_os'] })
+    assert.equal(result.eligible, false)
+    assert.equal(result.unsupportedOs, true)
+  })
+
+  it('combines multiple failing checks', () => {
+    const req: SkillRequirements = {
+      bins: ['nonexistent_bin_xyz'],
+      env: ['NONEXISTENT_ENV_ABC'],
+      os: ['nonexistent_os'],
+    }
+    const result = evaluateRequirements(req)
+    assert.equal(result.eligible, false)
+    assert.ok(result.reasons.length >= 3)
+    assert.ok(result.missingBins.length > 0)
+    assert.ok(result.missingEnv.length > 0)
+    assert.equal(result.unsupportedOs, true)
+  })
+})

package/src/lib/server/skill-eligibility.ts

@@ -0,0 +1,95 @@
+import { execSync } from 'child_process'
+import type { Skill, SkillRequirements } from '@/types'
+
+export interface SkillEligibilityResult {
+  eligible: boolean
+  missingBins: string[]
+  missingAnyBins: string[][]
+  missingEnv: string[]
+  unsupportedOs: boolean
+  reasons: string[]
+}
+
+const binaryCache = new Map<string, boolean>()
+
+function hasBinary(name: string): boolean {
+  const cached = binaryCache.get(name)
+  if (cached !== undefined) return cached
+  try {
+    execSync(`which ${name}`, { stdio: 'ignore', timeout: 2000 })
+    binaryCache.set(name, true)
+    return true
+  } catch {
+    binaryCache.set(name, false)
+    return false
+  }
+}
+
+/** Clear the binary cache (useful for tests or after installs). */
+export function clearBinaryCache(): void {
+  binaryCache.clear()
+}
+
+export function evaluateSkillEligibility(skill: Skill): SkillEligibilityResult {
+  const req = skill.skillRequirements
+  if (!req) return { eligible: true, missingBins: [], missingAnyBins: [], missingEnv: [], unsupportedOs: false, reasons: [] }
+
+  return evaluateRequirements(req)
+}
+
+export function evaluateRequirements(req: SkillRequirements): SkillEligibilityResult {
+  const reasons: string[] = []
+  const missingBins: string[] = []
+  const missingAnyBins: string[][] = []
+  const missingEnv: string[] = []
+  let unsupportedOs = false
+
+  // Check required binaries
+  if (req.bins?.length) {
+    for (const bin of req.bins) {
+      if (!hasBinary(bin)) {
+        missingBins.push(bin)
+      }
+    }
+    if (missingBins.length) {
+      reasons.push(`Missing binaries: ${missingBins.join(', ')}`)
+    }
+  }
+
+  // Check anyBins groups (at least one from each group must exist)
+  if (req.anyBins?.length) {
+    for (const group of req.anyBins) {
+      if (!group.some(hasBinary)) {
+        missingAnyBins.push(group)
+        reasons.push(`None of [${group.join(', ')}] found`)
+      }
+    }
+  }
+
+  // Check required environment variables
+  if (req.env?.length) {
+    for (const envVar of req.env) {
+      if (!process.env[envVar]) {
+        missingEnv.push(envVar)
+      }
+    }
+    if (missingEnv.length) {
+      reasons.push(`Missing env vars: ${missingEnv.join(', ')}`)
+    }
+  }
+
+  // Check OS compatibility
+  if (req.os?.length) {
+    if (!req.os.includes(process.platform)) {
+      unsupportedOs = true
+      reasons.push(`OS ${process.platform} not in [${req.os.join(', ')}]`)
+    }
+  }
+
+  const eligible = missingBins.length === 0
+    && missingAnyBins.length === 0
+    && missingEnv.length === 0
+    && !unsupportedOs
+
+  return { eligible, missingBins, missingAnyBins, missingEnv, unsupportedOs, reasons }
+}

package/src/lib/server/skill-prompt-budget.test.ts

@@ -0,0 +1,102 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { budgetSkillsForPrompt, buildSkillPromptText, MAX_SKILLS_IN_PROMPT, MAX_SKILLS_PROMPT_CHARS } from './skill-prompt-budget'
+import type { Skill } from '@/types'
+
+function makeSkill(id: string, overrides: Partial<Skill> = {}): Skill {
+  return {
+    name: id,
+    filename: `${id}.md`,
+    content: overrides.content ?? `Instructions for ${id} skill.`,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    ...overrides,
+  }
+}
+
+describe('budgetSkillsForPrompt', () => {
+  it('includes agent-bound skills first', () => {
+    const skills: Record<string, Skill> = {
+      weather: makeSkill('weather'),
+      github: makeSkill('github'),
+      coding: makeSkill('coding'),
+    }
+    const result = budgetSkillsForPrompt(skills, ['weather', 'coding'])
+    const included = result.filter((r) => r.included)
+    assert.equal(included.length, 3) // weather, coding (agent-bound) + github (eligible)
+    assert.equal(included[0].skill.name, 'weather')
+    assert.equal(included[1].skill.name, 'coding')
+  })
+
+  it('excludes ineligible skills (missing OS)', () => {
+    const skills: Record<string, Skill> = {
+      weather: makeSkill('weather', {
+        skillRequirements: { os: ['nonexistent_os'] },
+      }),
+    }
+    const result = budgetSkillsForPrompt(skills, ['weather'])
+    assert.equal(result[0].eligible, false)
+    assert.equal(result[0].included, false)
+  })
+
+  it('respects MAX_SKILLS_IN_PROMPT count limit', () => {
+    const skills: Record<string, Skill> = {}
+    const ids: string[] = []
+    for (let i = 0; i < MAX_SKILLS_IN_PROMPT + 10; i++) {
+      const id = `skill-${String(i).padStart(4, '0')}`
+      skills[id] = makeSkill(id, { content: 'x' })
+      ids.push(id)
+    }
+    const result = budgetSkillsForPrompt(skills, ids)
+    const included = result.filter((r) => r.included)
+    assert.equal(included.length, MAX_SKILLS_IN_PROMPT)
+    const excluded = result.filter((r) => !r.included && r.reason === 'skill count limit reached')
+    assert.equal(excluded.length, 10)
+  })
+
+  it('respects MAX_SKILLS_PROMPT_CHARS budget', () => {
+    // Create skills with large content that will exceed the budget
+    const bigContent = 'x'.repeat(10_000)
+    const skills: Record<string, Skill> = {
+      a: makeSkill('a', { content: bigContent }),
+      b: makeSkill('b', { content: bigContent }),
+      c: makeSkill('c', { content: bigContent }),
+      d: makeSkill('d', { content: bigContent }),
+    }
+    const result = budgetSkillsForPrompt(skills, ['a', 'b', 'c', 'd'])
+    const included = result.filter((r) => r.included)
+    // 10K * 3 = 30K, so at most 3 can fit
+    assert.ok(included.length <= 3)
+    const excluded = result.filter((r) => r.reason === 'character budget exceeded')
+    assert.ok(excluded.length >= 1)
+  })
+
+  it('prioritizes always-on skills over regular skills', () => {
+    const skills: Record<string, Skill> = {
+      regular: makeSkill('regular'),
+      alwaysOn: makeSkill('alwaysOn', { always: true }),
+    }
+    const result = budgetSkillsForPrompt(skills, [])
+    const included = result.filter((r) => r.included)
+    // always-on should come before regular
+    const alwaysIdx = included.findIndex((r) => r.skill.name === 'alwaysOn')
+    const regularIdx = included.findIndex((r) => r.skill.name === 'regular')
+    assert.ok(alwaysIdx < regularIdx, 'always-on skill should be prioritized')
+  })
+})
+
+describe('buildSkillPromptText', () => {
+  it('builds formatted prompt text', () => {
+    const skills: Record<string, Skill> = {
+      weather: makeSkill('weather', { content: 'Use wttr.in for weather queries.' }),
+    }
+    const text = buildSkillPromptText(skills, ['weather'])
+    assert.ok(text.includes('### weather'))
+    assert.ok(text.includes('Use wttr.in for weather queries.'))
+  })
+
+  it('returns empty string for no matching skills', () => {
+    const text = buildSkillPromptText({}, ['nonexistent'])
+    assert.equal(text, '')
+  })
+})

package/src/lib/server/skill-prompt-budget.ts

@@ -0,0 +1,125 @@
+import type { Skill } from '@/types'
+import { evaluateSkillEligibility } from './skill-eligibility'
+
+/** Maximum number of skills injected into the system prompt. */
+export const MAX_SKILLS_IN_PROMPT = 150
+
+/** Maximum total characters of skill content in the system prompt. */
+export const MAX_SKILLS_PROMPT_CHARS = 30_000
+
+export interface BudgetedSkill {
+  skill: Skill
+  eligible: boolean
+  included: boolean
+  reason?: string
+}
+
+/**
+ * Filter and budget skills for prompt injection.
+ * Priority order:
+ *   1. Agent-bound skills (skillIds) — always first
+ *   2. `always: true` skills — global skills marked as always-on
+ *   3. Other eligible skills — sorted by name
+ *
+ * Skills are filtered by eligibility (requirements met) and then by budget
+ * (count and character limits).
+ */
+export function budgetSkillsForPrompt(
+  skills: Record<string, Skill>,
+  agentSkillIds: string[],
+): BudgetedSkill[] {
+  const results: BudgetedSkill[] = []
+  const included: BudgetedSkill[] = []
+  let totalChars = 0
+
+  // Sort skills into priority buckets
+  const agentBound: Skill[] = []
+  const alwaysOn: Skill[] = []
+  const rest: Skill[] = []
+
+  for (const skillId of agentSkillIds) {
+    const skill = skills[skillId]
+    if (skill) agentBound.push(skill)
+  }
+
+  for (const skill of Object.values(skills)) {
+    if (agentSkillIds.includes(skill.name || '')) continue
+    if (skill.always) alwaysOn.push(skill)
+    else rest.push(skill)
+  }
+
+  // Sort non-agent skills by name for deterministic ordering
+  alwaysOn.sort((a, b) => a.name.localeCompare(b.name))
+  rest.sort((a, b) => a.name.localeCompare(b.name))
+
+  const orderedSkills = [...agentBound, ...alwaysOn, ...rest]
+
+  for (const skill of orderedSkills) {
+    const eligibility = evaluateSkillEligibility(skill)
+
+    if (!eligibility.eligible) {
+      results.push({ skill, eligible: false, included: false, reason: eligibility.reasons[0] })
+      continue
+    }
+
+    const contentLen = (skill.content || '').length + (skill.name || '').length + 12 // "## Skill: " prefix
+    if (included.length >= MAX_SKILLS_IN_PROMPT) {
+      results.push({ skill, eligible: true, included: false, reason: 'skill count limit reached' })
+      continue
+    }
+
+    if (totalChars + contentLen > MAX_SKILLS_PROMPT_CHARS) {
+      results.push({ skill, eligible: true, included: false, reason: 'character budget exceeded' })
+      continue
+    }
+
+    totalChars += contentLen
+    const entry: BudgetedSkill = { skill, eligible: true, included: true }
+    results.push(entry)
+    included.push(entry)
+  }
+
+  return results
+}
+
+/**
+ * Prescriptive skill adherence header.
+ * This tells the model exactly when and how to use skills — the key difference
+ * vs OpenClaw's superior skill following (1-2 tool calls vs 3-5).
+ */
+const SKILL_ADHERENCE_HEADER = `## Skills
+
+Before responding, scan the skills listed below.
+- If exactly one skill clearly applies to the user's request: follow its instructions directly.
+- If multiple skills could apply: choose the most specific one, then follow it.
+- If no skill applies: use your general tools (web search, shell, files, etc.) as normal.
+
+When following a skill:
+- Execute the skill's recommended commands or approach first, before falling back to generic tools.
+- Prefer the skill's specific tool/command (e.g. \`curl wttr.in\` for weather) over generic web search.
+- Aim for minimal tool calls — combine steps where possible.
+- Respect rate limits: prefer fewer, larger operations over many small ones.
+
+Available skills:`
+
+/**
+ * Build the prompt text for included skills, respecting budget limits.
+ * Returns the text to inject into the system prompt.
+ */
+export function buildSkillPromptText(
+  skills: Record<string, Skill>,
+  agentSkillIds: string[],
+): string {
+  const budgeted = budgetSkillsForPrompt(skills, agentSkillIds)
+  const skillParts: string[] = []
+
+  for (const entry of budgeted) {
+    if (!entry.included) continue
+    if (!entry.skill.content) continue
+    skillParts.push(`### ${entry.skill.name}\n${entry.skill.content}`)
+  }
+
+  if (skillParts.length === 0) return ''
+
+  return `${SKILL_ADHERENCE_HEADER}\n\n${skillParts.join('\n\n')}`
+}

package/src/lib/server/skills-normalize.test.ts

@@ -0,0 +1,54 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { normalizeSkillPayload } from './skills-normalize'
+
+test('normalizeSkillPayload parses openclaw frontmatter metadata', () => {
+  const normalized = normalizeSkillPayload({
+    content: `---
+name: github-sync
+description: Sync GitHub issues into tasks.
+version: 1.2.3
+metadata:
+  openclaw:
+    requires:
+      env:
+        - GITHUB_TOKEN
+      bins:
+        - curl
+    primaryEnv: GITHUB_TOKEN
+    homepage: https://example.com/github-sync
+    install:
+      - kind: brew
+        formula: gh
+        bins: [gh]
+---
+# Sync issues
+
+Use the GitHub API.`,
+  })
+
+  assert.equal(normalized.name, 'github-sync')
+  assert.equal(normalized.description, 'Sync GitHub issues into tasks.')
+  assert.equal(normalized.version, '1.2.3')
+  assert.equal(normalized.primaryEnv, 'GITHUB_TOKEN')
+  assert.equal(normalized.homepage, 'https://example.com/github-sync')
+  assert.equal(normalized.sourceFormat, 'openclaw')
+  assert.match(normalized.content, /# Sync issues/)
+  assert.equal(normalized.skillRequirements?.env?.[0], 'GITHUB_TOKEN')
+  assert.equal(normalized.installOptions?.[0]?.kind, 'brew')
+  assert.equal(normalized.installOptions?.[0]?.bins?.[0], 'gh')
+})
+
+test('normalizeSkillPayload flags undeclared env vars in skill content', () => {
+  const normalized = normalizeSkillPayload({
+    content: `---
+name: env-check
+description: Reads process env.
+---
+Run with \`process.env.GITHUB_TOKEN\` and \`process.env.OPENAI_API_KEY\`.`,
+  })
+
+  assert.equal(normalized.security?.level, 'high')
+  assert.ok(normalized.security?.missingDeclarations?.includes('GITHUB_TOKEN'))
+  assert.ok(normalized.security?.missingDeclarations?.includes('OPENAI_API_KEY'))
+})