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, stopSkillSync } from './skills/remote-sync'
 import { seedDefaultSkills } from './skills/seed'
 import { registry } from './tools/registry'
 import { VERSION } from './version'
@@ -111,12 +112,14 @@ export class Application {
     )
 
     this.logStartupSummary(controllerServerStarted)
+    startSkillSync()
 
     metrics.log('http_server.started', { version: VERSION })
   }
 
   stop(reason?: string): void {
     logger.info('Shutting down server...', { reason })
+    stopSkillSync()
 
     // Immediate exit without graceful shutdown. Chromium may kill us on update/restart,
     // and we need to free the port instantly so the HTTP port doesn't keep switching.

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

@@ -0,0 +1,265 @@
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { SKILLS_LIMITS } from '@browseros/shared/constants/limits'
+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 { safeSkillDir } from './service'
+import type {
+  ManagedSkillRecord,
+  RemoteSkillCatalog,
+  RemoteSkillEntry,
+  SkillManifest,
+} from './types'
+
+export const MANIFEST_FILE = '.remote-manifest.json'
+
+let syncTimer: ReturnType<typeof setInterval> | null = null
+
+export function extractVersion(content: string): string {
+  const match = content.match(/^\s*version:\s*["']?([^"'\n]+)["']?/m)
+  return match?.[1]?.trim() || '1.0'
+}
+
+export function contentHash(content: string): string {
+  return createHash('sha256').update(content).digest('hex')
+}
+
+function getManifestPath(): string {
+  return join(getSkillsDir(), MANIFEST_FILE)
+}
+
+function isValidManifest(data: unknown): data is SkillManifest {
+  if (typeof data !== 'object' || data === null) return false
+  const d = data as Record<string, unknown>
+  return typeof d.lastSyncedAt === 'string' && typeof d.skills === 'object' && d.skills !== null
+}
+
+function isValidSkillEntry(entry: unknown): entry is RemoteSkillEntry {
+  if (typeof entry !== 'object' || entry === null) return false
+  const e = entry as Record<string, unknown>
+  return (
+    typeof e.id === 'string' &&
+    typeof e.version === 'string' &&
+    typeof e.content === 'string'
+  )
+}
+
+function isValidCatalog(data: unknown): data is RemoteSkillCatalog {
+  if (typeof data !== 'object' || data === null) return false
+  const d = data as Record<string, unknown>
+  return (
+    typeof d.version === 'number' &&
+    Array.isArray(d.skills) &&
+    d.skills.every(isValidSkillEntry)
+  )
+}
+
+export async function loadManifest(): Promise<SkillManifest> {
+  try {
+    const raw = await readFile(getManifestPath(), 'utf-8')
+    const parsed: unknown = JSON.parse(raw)
+    if (!isValidManifest(parsed)) {
+      logger.warn('Invalid manifest file, resetting')
+      return { lastSyncedAt: '', skills: {} }
+    }
+    return parsed
+  } catch {
+    return { lastSyncedAt: '', skills: {} }
+  }
+}
+
+export 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
+    }
+    const text = await response.text()
+    if (text.length > SKILLS_LIMITS.MAX_CATALOG_BYTES) {
+      logger.warn('Remote skill catalog response too large', {
+        size: text.length,
+      })
+      return null
+    }
+    const data: unknown = JSON.parse(text)
+    if (!isValidCatalog(data)) {
+      logger.warn('Remote skill catalog has invalid format')
+      return null
+    }
+    return data
+  } 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 {
+    const safeDir = safeSkillDir(skillId)
+    return await readFile(join(safeDir, 'SKILL.md'), 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+export async function writeSkillFile(
+  skillId: string,
+  content: string,
+): Promise<void> {
+  const safeDir = safeSkillDir(skillId)
+  await mkdir(safeDir, { recursive: true })
+  await writeFile(join(safeDir, 'SKILL.md'), content)
+}
+
+export 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) {
+    try {
+      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) {
+        result.skipped++
+        continue
+      }
+
+      if (localRecord.version === remoteSkill.version) {
+        continue
+      }
+
+      if (isSkillCustomized(remoteSkill.id, localContent, manifest)) {
+        result.skipped++
+        continue
+      }
+
+      await installSkill(remoteSkill, manifest)
+      result.updated++
+    } catch (err) {
+      logger.warn('Failed to sync skill', {
+        id: remoteSkill.id,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  if (result.installed > 0 || result.updated > 0) {
+    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 installSkill(skill, manifest)
+      seeded++
+    } catch (err) {
+      logger.warn('Failed to seed remote skill', {
+        id: skill.id,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  if (seeded === 0) return false
+
+  manifest.lastSyncedAt = new Date().toISOString()
+  await saveManifest(manifest)
+  logger.info(`Seeded ${seeded}/${catalog.skills.length} skills from remote catalog`)
+
+  return seeded === catalog.skills.length
+}
+
+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)
+
+  syncTimer.unref()
+}
+
+export function stopSkillSync(): void {
+  if (syncTimer) {
+    clearInterval(syncTimer)
+    syncTimer = null
+  }
+}

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

@@ -1,8 +1,16 @@
-import { mkdir, readdir, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { readdir } from 'node:fs/promises'
 import { getSkillsDir } from '../lib/browseros-dir'
 import { logger } from '../lib/logger'
 import { DEFAULT_SKILLS } from './defaults'
+import {
+  contentHash,
+  extractVersion,
+  installSkill,
+  loadManifest,
+  saveManifest,
+  seedFromRemote,
+  writeSkillFile,
+} from './remote-sync'
 
 async function hasExistingSkills(skillsDir: string): Promise<boolean> {
   try {
@@ -17,12 +25,20 @@ 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()
   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)
+      const version = extractVersion(skill.content)
+      await writeSkillFile(skill.id, skill.content)
+      manifest.skills[skill.id] = {
+        version,
+        contentHash: contentHash(skill.content),
+      }
       seeded++
     } catch (err) {
       logger.warn('Failed to seed skill', {
@@ -33,6 +49,7 @@ export async function seedDefaultSkills(): Promise<void> {
   }
 
   if (seeded > 0) {
-    logger.info(`Seeded ${seeded} default skills`)
+    await saveManifest(manifest)
+    logger.info(`Seeded ${seeded} default skills (bundled)`)
   }
 }

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

@@ -19,8 +19,7 @@ export function slugify(name: string): string {
     .replace(/^-|-$/g, '')
 }
 
-// Prevents path traversal — ensures resolved path stays inside skills directory
-function safeSkillDir(id: string): string {
+export function safeSkillDir(id: string): string {
   const skillsDir = getSkillsDir()
   const resolved = resolve(skillsDir, id)
   if (!resolved.startsWith(`${skillsDir}${sep}`)) {

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>
+}