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,188 @@
+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 { RemoteSkillCatalog, RemoteSkillEntry } from './types'
+
+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'
+}
+
+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)
+  )
+}
+
+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 contentLength = Number(response.headers.get('content-length') ?? 0)
+    if (contentLength > SKILLS_LIMITS.MAX_CATALOG_BYTES) {
+      logger.warn('Remote skill catalog Content-Length too large', {
+        contentLength,
+      })
+      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
+  }
+}
+
+async function getLocalVersion(skillId: string): Promise<string | null> {
+  try {
+    const safeDir = safeSkillDir(skillId)
+    const content = await readFile(join(safeDir, 'SKILL.md'), 'utf-8')
+    return extractVersion(content)
+  } 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 syncRemoteSkills(): Promise<{
+  installed: number
+  updated: number
+}> {
+  const result = { installed: 0, updated: 0 }
+  const catalog = await fetchRemoteCatalog()
+  if (!catalog) return result
+
+  for (const remoteSkill of catalog.skills) {
+    try {
+      const localVersion = await getLocalVersion(remoteSkill.id)
+
+      if (!localVersion) {
+        await writeSkillFile(remoteSkill.id, remoteSkill.content)
+        result.installed++
+        continue
+      }
+
+      if (localVersion === remoteSkill.version) {
+        continue
+      }
+
+      await writeSkillFile(remoteSkill.id, remoteSkill.content)
+      result.updated++
+    } catch (err) {
+      logger.warn('Failed to sync skill', {
+        id: remoteSkill.id,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  return result
+}
+
+export async function seedFromRemote(): Promise<boolean> {
+  const catalog = await fetchRemoteCatalog()
+  if (!catalog || catalog.skills.length === 0) return false
+
+  let seeded = 0
+
+  for (const skill of catalog.skills) {
+    try {
+      await writeSkillFile(skill.id, 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) {
+    logger.info(`Seeded ${seeded}/${catalog.skills.length} skills from remote catalog`)
+  }
+
+  return seeded === catalog.skills.length
+}
+
+async function runSync(): Promise<void> {
+  try {
+    const { installed, updated } = await syncRemoteSkills()
+    if (installed > 0 || updated > 0) {
+      logger.info('Remote skill sync completed', { installed, updated })
+    }
+  } catch (err) {
+    logger.warn('Skill sync failed', {
+      error: err instanceof Error ? err.message : String(err),
+    })
+  }
+}
+
+export function startSkillSync(): void {
+  if (syncTimer) return
+
+  runSync()
+
+  syncTimer = setInterval(runSync, 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,8 @@
-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 { seedFromRemote, writeSkillFile } from './remote-sync'
 
 async function hasExistingSkills(skillsDir: string): Promise<boolean> {
   try {
@@ -17,12 +17,13 @@ export async function seedDefaultSkills(): Promise<void> {
   const skillsDir = getSkillsDir()
   if (await hasExistingSkills(skillsDir)) return
 
+  const remoteSucceeded = await seedFromRemote()
+  if (remoteSucceeded) 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)
+      await writeSkillFile(skill.id, skill.content)
       seeded++
     } catch (err) {
       logger.warn('Failed to seed skill', {
@@ -33,6 +34,6 @@ export async function seedDefaultSkills(): Promise<void> {
   }
 
   if (seeded > 0) {
-    logger.info(`Seeded ${seeded} default skills`)
+    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,15 @@ 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[]
+}
+

packages/browseros-agent/apps/server/tests/skills/flows.test.ts

@@ -0,0 +1,90 @@
+/**
+ * E2E flow tests against live CDN.
+ */
+
+import { afterAll, beforeAll, describe, it, mock } from 'bun:test'
+import assert from 'node:assert'
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+let testDir: string
+
+mock.module('../../src/lib/browseros-dir', () => ({
+  getSkillsDir: () => testDir,
+}))
+
+mock.module('../../src/env', () => ({
+  INLINED_ENV: {
+    SKILLS_CATALOG_URL: 'https://cdn.browseros.com/skills/v1/catalog.json',
+  },
+}))
+
+const { seedFromRemote, syncRemoteSkills } =
+  await import('../../src/skills/remote-sync')
+
+async function listSkills(): Promise<string[]> {
+  const entries = await readdir(testDir)
+  return entries.filter((e) => !e.startsWith('.')).sort()
+}
+
+beforeAll(async () => {
+  testDir = join(tmpdir(), `flow-test-${Date.now()}`)
+  await mkdir(testDir, { recursive: true })
+})
+
+afterAll(async () => {
+  await rm(testDir, { recursive: true, force: true })
+})
+
+describe('Flow tests against live CDN', () => {
+  it('seeds all skills from CDN on fresh install', async () => {
+    const result = await seedFromRemote()
+    assert.strictEqual(result, true)
+    const skills = await listSkills()
+    assert.strictEqual(skills.length, 12)
+  })
+
+  it('sync does nothing when already up to date', async () => {
+    const result = await syncRemoteSkills()
+    assert.strictEqual(result.installed, 0)
+    assert.strictEqual(result.updated, 0)
+  })
+
+  it('remote overwrites local edits when version differs', async () => {
+    const skillPath = join(testDir, 'summarize-page', 'SKILL.md')
+    const original = await readFile(skillPath, 'utf-8')
+
+    // User edits the file AND we fake a version mismatch
+    const edited = original.replace(/version: "1.0"/, 'version: "0.9"') + '\n## My Notes\n'
+    await writeFile(skillPath, edited)
+
+    const result = await syncRemoteSkills()
+    assert.strictEqual(result.updated >= 1, true)
+
+    const afterSync = await readFile(skillPath, 'utf-8')
+    assert.ok(!afterSync.includes('My Notes'))
+  })
+
+  it('installs skill deleted locally', async () => {
+    await rm(join(testDir, 'save-page'), { recursive: true })
+
+    const result = await syncRemoteSkills()
+    assert.strictEqual(result.installed, 1)
+
+    const content = await readFile(join(testDir, 'save-page', 'SKILL.md'), 'utf-8')
+    assert.ok(content.includes('name: save-page'))
+  })
+
+  it('user-created skill is never touched', async () => {
+    const customDir = join(testDir, 'my-workflow')
+    await mkdir(customDir, { recursive: true })
+    const custom = '---\nname: my-workflow\ndescription: custom\n---\n# Mine\n'
+    await writeFile(join(customDir, 'SKILL.md'), custom)
+
+    await syncRemoteSkills()
+
+    const afterSync = await readFile(join(customDir, 'SKILL.md'), 'utf-8')
+    assert.strictEqual(afterSync, custom)
+  })
+})