feat: remote skill download and auto-sync

packages/browseros-agent/apps/server/src/env.ts

@@ -19,6 +19,7 @@ export const INLINED_ENV = {
   CODEGEN_SERVICE_URL: process.env.CODEGEN_SERVICE_URL,
   POSTHOG_API_KEY: process.env.POSTHOG_API_KEY,
   BROWSEROS_CONFIG_URL: process.env.BROWSEROS_CONFIG_URL,
+  SKILLS_CATALOG_URL: process.env.SKILLS_CATALOG_URL,
 } as const
 
 export const REQUIRED_FOR_PRODUCTION = [

packages/browseros-agent/apps/server/src/main.ts

@@ -28,6 +28,7 @@ import { fetchDailyRateLimit } from './lib/rate-limiter/fetch-config'
 import { RateLimiter } from './lib/rate-limiter/rate-limiter'
 import { Sentry } from './lib/sentry'
 import { seedSoulTemplate } from './lib/soul'
+import { startSkillSync } from './skills/remote-sync'
 import { seedDefaultSkills } from './skills/seed'
 import { registry } from './tools/registry'
 import { VERSION } from './version'
@@ -111,6 +112,7 @@ export class Application {
     )
 
     this.logStartupSummary(controllerServerStarted)
+    startSkillSync()
 
     metrics.log('http_server.started', { version: VERSION })
   }

packages/browseros-agent/apps/server/src/skills/remote-sync.ts

@@ -0,0 +1,214 @@
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { TIMEOUTS } from '@browseros/shared/constants/timeouts'
+import { EXTERNAL_URLS } from '@browseros/shared/constants/urls'
+import { INLINED_ENV } from '../env'
+import { getSkillsDir } from '../lib/browseros-dir'
+import { logger } from '../lib/logger'
+import type {
+  ManagedSkillRecord,
+  RemoteSkillCatalog,
+  RemoteSkillEntry,
+  SkillManifest,
+} from './types'
+
+const MANIFEST_FILE = '.remote-manifest.json'
+
+let syncTimer: ReturnType<typeof setInterval> | null = null
+
+function contentHash(content: string): string {
+  return createHash('sha256').update(content).digest('hex')
+}
+
+function getManifestPath(): string {
+  return join(getSkillsDir(), MANIFEST_FILE)
+}
+
+export async function loadManifest(): Promise<SkillManifest> {
+  try {
+    const raw = await readFile(getManifestPath(), 'utf-8')
+    return JSON.parse(raw) as SkillManifest
+  } catch {
+    return { lastSyncedAt: '', skills: {} }
+  }
+}
+
+async function saveManifest(manifest: SkillManifest): Promise<void> {
+  await writeFile(getManifestPath(), JSON.stringify(manifest, null, 2))
+}
+
+function getCatalogUrl(): string {
+  return INLINED_ENV.SKILLS_CATALOG_URL || EXTERNAL_URLS.SKILLS_CATALOG
+}
+
+export async function fetchRemoteCatalog(): Promise<RemoteSkillCatalog | null> {
+  try {
+    const response = await fetch(getCatalogUrl(), {
+      signal: AbortSignal.timeout(TIMEOUTS.SKILLS_FETCH),
+    })
+    if (!response.ok) {
+      logger.warn('Failed to fetch remote skill catalog', {
+        status: response.status,
+      })
+      return null
+    }
+    return (await response.json()) as RemoteSkillCatalog
+  } catch (err) {
+    logger.debug('Remote skill catalog unavailable', {
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return null
+  }
+}
+
+function isSkillCustomized(
+  skillId: string,
+  currentContent: string,
+  manifest: SkillManifest,
+): boolean {
+  const record = manifest.skills[skillId]
+  if (!record) return false
+  return contentHash(currentContent) !== record.contentHash
+}
+
+async function readSkillContent(skillId: string): Promise<string | null> {
+  try {
+    return await readFile(
+      join(getSkillsDir(), skillId, 'SKILL.md'),
+      'utf-8',
+    )
+  } catch {
+    return null
+  }
+}
+
+async function writeSkillFile(
+  skillId: string,
+  content: string,
+): Promise<void> {
+  const targetDir = join(getSkillsDir(), skillId)
+  await mkdir(targetDir, { recursive: true })
+  await writeFile(join(targetDir, 'SKILL.md'), content)
+}
+
+async function installSkill(
+  skill: RemoteSkillEntry,
+  manifest: SkillManifest,
+): Promise<void> {
+  await writeSkillFile(skill.id, skill.content)
+  manifest.skills[skill.id] = {
+    version: skill.version,
+    contentHash: contentHash(skill.content),
+  }
+}
+
+export async function syncRemoteSkills(): Promise<{
+  installed: number
+  updated: number
+  skipped: number
+}> {
+  const result = { installed: 0, updated: 0, skipped: 0 }
+  const catalog = await fetchRemoteCatalog()
+  if (!catalog) return result
+
+  const manifest = await loadManifest()
+
+  for (const remoteSkill of catalog.skills) {
+    const localContent = await readSkillContent(remoteSkill.id)
+    const localRecord: ManagedSkillRecord | undefined =
+      manifest.skills[remoteSkill.id]
+
+    if (!localContent) {
+      await installSkill(remoteSkill, manifest)
+      result.installed++
+      continue
+    }
+
+    if (!localRecord) {
+      // Skill exists locally but isn't tracked — treat as user-managed
+      result.skipped++
+      continue
+    }
+
+    if (localRecord.version === remoteSkill.version) {
+      continue
+    }
+
+    if (isSkillCustomized(remoteSkill.id, localContent, manifest)) {
+      result.skipped++
+      continue
+    }
+
+    await installSkill(remoteSkill, manifest)
+    result.updated++
+  }
+
+  manifest.lastSyncedAt = new Date().toISOString()
+  await saveManifest(manifest)
+
+  return result
+}
+
+export async function seedFromRemote(): Promise<boolean> {
+  const catalog = await fetchRemoteCatalog()
+  if (!catalog || catalog.skills.length === 0) return false
+
+  const manifest = await loadManifest()
+  let seeded = 0
+
+  for (const skill of catalog.skills) {
+    try {
+      await writeSkillFile(skill.id, skill.content)
+      manifest.skills[skill.id] = {
+        version: skill.version,
+        contentHash: contentHash(skill.content),
+      }
+      seeded++
+    } catch (err) {
+      logger.warn('Failed to seed remote skill', {
+        id: skill.id,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  if (seeded > 0) {
+    manifest.lastSyncedAt = new Date().toISOString()
+    await saveManifest(manifest)
+    logger.info(`Seeded ${seeded} skills from remote catalog`)
+  }
+
+  return seeded > 0
+}
+
+export function startSkillSync(): void {
+  if (syncTimer) return
+
+  syncTimer = setInterval(async () => {
+    try {
+      const { installed, updated, skipped } = await syncRemoteSkills()
+      if (installed > 0 || updated > 0) {
+        logger.info('Remote skill sync completed', {
+          installed,
+          updated,
+          skipped,
+        })
+      }
+    } catch (err) {
+      logger.warn('Skill sync failed', {
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }, TIMEOUTS.SKILLS_SYNC_INTERVAL)
+
+  // Don't block process exit
+  syncTimer.unref()
+}
+
+export function stopSkillSync(): void {
+  if (syncTimer) {
+    clearInterval(syncTimer)
+    syncTimer = null
+  }
+}

packages/browseros-agent/apps/server/src/skills/seed.ts

@@ -1,8 +1,11 @@
+import { createHash } from 'node:crypto'
 import { mkdir, readdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { getSkillsDir } from '../lib/browseros-dir'
 import { logger } from '../lib/logger'
 import { DEFAULT_SKILLS } from './defaults'
+import { loadManifest, seedFromRemote } from './remote-sync'
+import type { SkillManifest } from './types'
 
 async function hasExistingSkills(skillsDir: string): Promise<boolean> {
   try {
@@ -13,16 +16,18 @@ async function hasExistingSkills(skillsDir: string): Promise<boolean> {
   }
 }
 
-export async function seedDefaultSkills(): Promise<void> {
+async function seedFromBundled(manifest: SkillManifest): Promise<void> {
   const skillsDir = getSkillsDir()
-  if (await hasExistingSkills(skillsDir)) return
-
   let seeded = 0
   for (const skill of DEFAULT_SKILLS) {
     try {
       const targetDir = join(skillsDir, skill.id)
       await mkdir(targetDir, { recursive: true })
       await writeFile(join(targetDir, 'SKILL.md'), skill.content)
+      manifest.skills[skill.id] = {
+        version: '1.0',
+        contentHash: createHash('sha256').update(skill.content).digest('hex'),
+      }
       seeded++
     } catch (err) {
       logger.warn('Failed to seed skill', {
@@ -33,6 +38,20 @@ export async function seedDefaultSkills(): Promise<void> {
   }
 
   if (seeded > 0) {
-    logger.info(`Seeded ${seeded} default skills`)
+    logger.info(`Seeded ${seeded} default skills (bundled)`)
   }
 }
+
+export async function seedDefaultSkills(): Promise<void> {
+  const skillsDir = getSkillsDir()
+  if (await hasExistingSkills(skillsDir)) return
+
+  const remoteSucceeded = await seedFromRemote()
+  if (remoteSucceeded) return
+
+  const manifest = await loadManifest()
+  await seedFromBundled(manifest)
+
+  const manifestPath = join(skillsDir, '.remote-manifest.json')
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2))
+}

packages/browseros-agent/apps/server/src/skills/types.ts

@@ -38,3 +38,24 @@ export type CreateSkillInput = {
 export type UpdateSkillInput = Partial<CreateSkillInput> & {
   enabled?: boolean
 }
+
+export type RemoteSkillEntry = {
+  id: string
+  version: string
+  content: string
+}
+
+export type RemoteSkillCatalog = {
+  version: number
+  skills: RemoteSkillEntry[]
+}
+
+export type ManagedSkillRecord = {
+  version: string
+  contentHash: string
+}
+
+export type SkillManifest = {
+  lastSyncedAt: string
+  skills: Record<string, ManagedSkillRecord>
+}