@yeaft/webchat-agent 1.0.443 → 1.0.445

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.443",
+  "version": "1.0.445",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/startup-maintenance.js

@@ -0,0 +1,52 @@
+import { execFile } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { promisify } from 'node:util';
+import { resolveWindowsNpmCliPath } from './upgrade-command.js';
+
+const execFileAsync = promisify(execFile);
+
+export const YEAFT_SKILLS_UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+export function execHiddenFileAsync(command, args = [], options = {}) {
+  return execFileAsync(command, args, {
+    ...options,
+    shell: false,
+    windowsHide: true,
+  });
+}
+
+export function resolveNpmInvocation({
+  platform = process.platform,
+  nodePath = process.execPath,
+  resolveWindowsNpmCliPathFn = resolveWindowsNpmCliPath,
+} = {}) {
+  if (platform === 'win32') {
+    const npmCliPath = resolveWindowsNpmCliPathFn(nodePath);
+    if (!npmCliPath) {
+      throw new Error('npm JavaScript CLI entry point could not be resolved');
+    }
+    return { command: nodePath, argsPrefix: [npmCliPath] };
+  }
+  return { command: 'npm', argsPrefix: [] };
+}
+
+export function shouldRunPeriodicCheck(
+  markerPath,
+  intervalMs = YEAFT_SKILLS_UPDATE_CHECK_INTERVAL_MS,
+  now = Date.now,
+) {
+  try {
+    const checkedAt = JSON.parse(readFileSync(markerPath, 'utf8'))?.checkedAt;
+    return !Number.isFinite(checkedAt) || now() - checkedAt >= intervalMs;
+  } catch {
+    return true;
+  }
+}
+
+export function writePeriodicCheckMarker(markerPath, now = Date.now) {
+  const checkedAt = now();
+  writeFileSync(markerPath, JSON.stringify({
+    checkedAt,
+    checkedAtIso: new Date(checkedAt).toISOString(),
+  }, null, 2));
+}

package/yeaft/plugins.js

@@ -133,16 +133,30 @@ export function buildPluginCatalog({ toolRegistry, skillManager, mcpConfig, mcpM
       .sort((a, b) => a.label.localeCompare(b.label))
     : [];
 
-  const skills = typeof skillManager?.list === 'function'
-    ? skillManager.list()
-      .map(skill => ({
-        id: skill.name,
-        label: skill.name,
-        description: skill.description || '',
-        category: skill.category || null,
-      }))
-      .sort((a, b) => a.label.localeCompare(b.label))
-    : [];
+  // Runtime authorization is keyed by Skill name, so this catalog must expose
+  // only the effective layered entry per name. Source-level rows belong to the
+  // management surface below; otherwise a project override would render two
+  // allowlist toggles that both mutate the same name.
+  const skills = (typeof skillManager?.list === 'function' ? skillManager.list() : [])
+    .map(skill => ({
+      id: skill.name,
+      label: skill.name,
+      description: skill.description || '',
+      category: skill.category || null,
+      tier: skill.tier || null,
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label));
+
+  const skillSources = (typeof skillManager?.listSources === 'function' ? skillManager.listSources() : [])
+    .map(skill => ({
+      id: skill.id,
+      name: skill.name,
+      label: skill.name,
+      description: skill.description || '',
+      tier: skill.tier || null,
+      managed: skill.managed === true,
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label) || String(a.id).localeCompare(String(b.id)));
 
   const statusByName = new Map((mcpManager?.status?.() || [])
     .map(status => [status.name, status]));
@@ -166,5 +180,5 @@ export function buildPluginCatalog({ toolRegistry, skillManager, mcpConfig, mcpM
     })
     .sort((a, b) => a.label.localeCompare(b.label));
 
-  return { tools, skills, mcpServers };
+  return { tools, skills, skillSources, mcpServers };
 }

package/yeaft/skills.js

@@ -55,7 +55,7 @@
  * Reference: yeaft-yeaft-design.md §8, yeaft-yeaft-core-systems.md
  */
 
-import { existsSync, readFileSync, readdirSync, writeFileSync, unlinkSync, mkdirSync, statSync, realpathSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync, unlinkSync, mkdirSync, statSync, lstatSync, realpathSync } from 'fs';
 import { join, basename, sep, dirname, resolve, delimiter } from 'path';
 import { platform, homedir } from 'os';
 import { fileURLToPath } from 'url';
@@ -247,6 +247,189 @@ function pathIsInside(childPath, parentPath) {
   return child === parent || child.startsWith(parent + sep);
 }
 
+const MANAGED_SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$/;
+const MAX_MANAGED_SKILL_TEXT_LENGTH = 64 * 1024;
+
+function normalizeManagedSkillInput(input = {}) {
+  const name = typeof input.name === 'string' ? input.name.trim() : '';
+  if (!MANAGED_SKILL_NAME_RE.test(name)) {
+    throw new Error('skill name must start with a letter or digit and use only letters, digits, dots, dashes, or underscores');
+  }
+  const description = typeof input.description === 'string' ? input.description.trim() : '';
+  const trigger = typeof input.trigger === 'string' ? input.trigger.trim() : '';
+  const content = typeof input.content === 'string' ? input.content.trim() : '';
+  if (!description) throw new Error('skill description is required');
+  if (!content) throw new Error('skill instructions are required');
+  if (/[\r\n]/.test(description) || /[\r\n]/.test(trigger)) {
+    throw new Error('skill description and trigger must be single-line text');
+  }
+  if ([description, trigger, content].some(value => value.length > MAX_MANAGED_SKILL_TEXT_LENGTH)) {
+    throw new Error('skill fields exceed the maximum allowed length');
+  }
+  return { name, description, trigger, content, mode: 'both' };
+}
+
+function assertNativeSkillRoot(rootDir, { create = true } = {}) {
+  const root = resolve(rootDir || '');
+  if (!root || root === resolve('.')) throw new Error('skill root is required');
+  if (existsSync(root)) {
+    const stat = lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('skill root must be a non-symbolic-link directory');
+  } else if (create) {
+    mkdirSync(root, { recursive: true });
+  } else {
+    return null;
+  }
+  try {
+    return realpathSync(root);
+  } catch {
+    throw new Error('skill root could not be resolved safely');
+  }
+}
+
+function managedSkillFilePath(rootDir, name, options) {
+  if (!MANAGED_SKILL_NAME_RE.test(name)) throw new Error('invalid skill name');
+  const root = assertNativeSkillRoot(rootDir, options);
+  if (!root) return null;
+  const filePath = resolve(root, `${name}.md`);
+  if (!pathIsInside(filePath, root) || filePath === root) throw new Error('invalid skill path');
+  if (existsSync(filePath)) {
+    let stat;
+    try {
+      stat = lstatSync(filePath);
+    } catch {
+      throw new Error('skill path could not be inspected safely');
+    }
+    if (stat.isSymbolicLink()) throw new Error('skill path must not be a symbolic link');
+  }
+  return filePath;
+}
+
+function isRemovableNativeSkill(skillPath, rootDir) {
+  if (!skillPath || !rootDir || !pathIsInside(skillPath, rootDir)) return false;
+  try {
+    const stat = lstatSync(skillPath);
+    return stat.isFile() && !stat.isSymbolicLink() && skillPath.toLowerCase().endsWith('.md');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a native Yeaft single-file skill within an explicitly selected scope.
+ * This deliberately does not edit bundled or borrowed Claude/Codex sources.
+ *
+ * @param {string} rootDir
+ * @param {{ name: string, description: string, trigger?: string, content: string }} input
+ * @returns {{ name: string, path: string }}
+ */
+export function createManagedSkill(rootDir, input) {
+  const skill = normalizeManagedSkillInput(input);
+  const filePath = managedSkillFilePath(rootDir, skill.name);
+  if (existsSync(filePath)) throw new Error(`skill "${skill.name}" already exists in this scope`);
+  writeFileSync(filePath, serializeSkill(skill), { encoding: 'utf8', flag: 'wx' });
+  return { name: skill.name, path: filePath };
+}
+
+/**
+ * Remove only a native single-file skill from the selected Yeaft scope.
+ * Directory skills and borrowed/project compatibility roots are intentionally
+ * left untouched because they may own references and unrelated project files.
+ *
+ * @param {string} rootDir
+ * @param {string} rawName
+ * @returns {{ name: string, removed: boolean }}
+ */
+export function removeManagedSkill(rootDir, rawName) {
+  const name = typeof rawName === 'string' ? rawName.trim() : '';
+  const root = assertNativeSkillRoot(rootDir, { create: false });
+  if (!root) return { name, removed: false };
+  const filePath = managedSkillFilePath(root, name, { create: false });
+  if (!filePath || !existsSync(filePath)) return { name, removed: false };
+  if (!isRemovableNativeSkill(filePath, root)) {
+    throw new Error('only native single-file skills can be removed here');
+  }
+  unlinkSync(filePath);
+  return { name, removed: true };
+}
+
+function managedProjectDirectory(parent, name, { create }) {
+  const candidate = join(parent, name);
+  if (!pathIsInside(candidate, parent)) throw new Error('invalid managed project Skill path');
+  if (!existsSync(candidate)) {
+    if (!create) return null;
+    // Create a single verified segment at a time. Recursive mkdir would follow
+    // a repository-controlled `.yeaft` link before we could inspect it.
+    mkdirSync(candidate);
+  }
+  let stat;
+  try {
+    stat = lstatSync(candidate);
+  } catch {
+    throw new Error('managed project Skill path could not be inspected safely');
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error('managed project Skill path must not contain a symbolic link');
+  }
+  let canonical;
+  try {
+    canonical = realpathSync(candidate);
+  } catch {
+    throw new Error('managed project Skill path could not be resolved safely');
+  }
+  if (!pathIsInside(canonical, parent) || canonical === parent) {
+    throw new Error('managed project Skill path escapes the project directory');
+  }
+  return canonical;
+}
+
+/**
+ * Resolve `<canonical workDir>/.yeaft/skills` without following any
+ * repository-controlled path segment. `workDir` itself is canonicalized first,
+ * so a configured workspace alias still identifies its real project root.
+ *
+ * @param {string} workDir
+ * @param {{ create?: boolean }} [options]
+ * @returns {string|null}
+ */
+export function resolveManagedProjectSkillRoot(workDir, { create = true } = {}) {
+  const lexicalWorkDir = resolve(workDir || '');
+  if (!workDir || lexicalWorkDir === resolve('.')) {
+    throw new Error('project directory is required for project-level skills');
+  }
+  let projectRoot;
+  try {
+    projectRoot = realpathSync(lexicalWorkDir);
+  } catch {
+    throw new Error('project directory could not be resolved safely');
+  }
+  let projectStat;
+  try {
+    projectStat = lstatSync(projectRoot);
+  } catch {
+    throw new Error('project directory could not be inspected safely');
+  }
+  if (!projectStat.isDirectory() || projectStat.isSymbolicLink()) {
+    throw new Error('project directory must be a non-symbolic-link directory');
+  }
+  const yeaftRoot = managedProjectDirectory(projectRoot, '.yeaft', { create });
+  if (!yeaftRoot) return null;
+  return managedProjectDirectory(yeaftRoot, 'skills', { create });
+}
+
+/** Create a native Skill in a verified project-level Yeaft root. */
+export function createManagedProjectSkill(workDir, input) {
+  const root = resolveManagedProjectSkillRoot(workDir, { create: true });
+  return createManagedSkill(root, input);
+}
+
+/** Remove a native Skill from a verified project-level Yeaft root. */
+export function removeManagedProjectSkill(workDir, name) {
+  const root = resolveManagedProjectSkillRoot(workDir, { create: false });
+  if (!root) return { name: typeof name === 'string' ? name.trim() : '', removed: false };
+  return removeManagedSkill(root, name);
+}
+
 function shouldIgnorePath(candidatePath, ignorePaths) {
   return ignorePaths.some(ignorePath => pathIsInside(candidatePath, ignorePath));
 }
@@ -333,8 +516,83 @@ function discoverSkills(rootDir, subPath = '', opts = {}) {
   return { skills, errors };
 }
 
+function secureWorkspacePath(workspaceRoot, relativePath, type) {
+  const lexicalRoot = resolve(workspaceRoot);
+  const lexicalTarget = resolve(lexicalRoot, relativePath);
+  if (!pathIsInside(lexicalTarget, lexicalRoot) || lexicalTarget === lexicalRoot) return null;
+
+  let canonicalCurrent;
+  let expectedCurrent;
+  let current = lexicalRoot;
+  try {
+    const rootStat = lstatSync(current);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return null;
+    canonicalCurrent = realpathSync(current);
+    expectedCurrent = canonicalCurrent;
+    for (const component of relativePath.split(/[\\/]+/)) {
+      if (!component || component === '.' || component === '..') return null;
+      current = join(current, component);
+      expectedCurrent = join(expectedCurrent, component);
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink() || realpathSync(current) !== expectedCurrent) return null;
+      if (current !== lexicalTarget && !stat.isDirectory()) return null;
+      if (current === lexicalTarget && ((type === 'directory' && !stat.isDirectory()) || (type === 'file' && !stat.isFile()))) {
+        return null;
+      }
+    }
+    return current;
+  } catch {
+    return null;
+  }
+}
+
+function listSecureWorkspaceDirectory(workspaceRoot, relativePath) {
+  const dir = secureWorkspacePath(workspaceRoot, relativePath, 'directory');
+  if (!dir) return null;
+  try {
+    return readdirSync(dir, { withFileTypes: true }).map(entry => ({
+      name: entry.name,
+      isFile: entry.isFile(),
+      isDirectory: entry.isDirectory(),
+      isSymbolicLink: entry.isSymbolicLink() || entry.isBlockDevice() || entry.isCharacterDevice()
+        || entry.isFIFO() || entry.isSocket(),
+    }));
+  } catch {
+    return null;
+  }
+}
+
+function readSecureWorkspaceFile(workspaceRoot, relativePath) {
+  const file = secureWorkspacePath(workspaceRoot, relativePath, 'file');
+  if (!file) return null;
+  try {
+    if (lstatSync(file).size > MAX_PROJECT_SKILL_BYTES) {
+      return { truncated: true, buffer: Buffer.alloc(0) };
+    }
+    const buffer = readFileSync(file);
+    if (secureWorkspacePath(workspaceRoot, relativePath, 'file') !== file) return null;
+    return buffer.length > MAX_PROJECT_SKILL_BYTES
+      ? { truncated: true, buffer: Buffer.alloc(0) }
+      : { truncated: false, buffer };
+  } catch {
+    return null;
+  }
+}
+
+function listSecureWorkspaceEntries(workspaceRoot, relativePath) {
+  const entries = listWorkspaceDirectory(workspaceRoot, relativePath);
+  if (entries || process.platform === 'linux') return entries;
+  return listSecureWorkspaceDirectory(workspaceRoot, relativePath);
+}
+
+function readSecureWorkspaceSkillFile(workspaceRoot, relativePath) {
+  const read = readWorkspaceFile(workspaceRoot, relativePath, { maxBytes: MAX_PROJECT_SKILL_BYTES });
+  if (read || process.platform === 'linux') return read;
+  return readSecureWorkspaceFile(workspaceRoot, relativePath);
+}
+
 function listWorkspaceSkillFiles(workspaceRoot, relativeDir) {
-  return (listWorkspaceDirectory(workspaceRoot, relativeDir) || [])
+  return (listSecureWorkspaceEntries(workspaceRoot, relativeDir) || [])
     .filter(entry => entry.isFile && !entry.isSymbolicLink)
     .map(entry => entry.name);
 }
@@ -343,15 +601,16 @@ function discoverWorkspaceSkills(workspaceRoot, skillsRelativeRoot, subPath = ''
   const skills = [];
   const errors = [];
   const relativeDir = subPath ? join(skillsRelativeRoot, subPath) : skillsRelativeRoot;
-  const entries = listWorkspaceDirectory(workspaceRoot, relativeDir);
+  const entries = listSecureWorkspaceEntries(workspaceRoot, relativeDir);
   if (!entries) return { skills, errors };
+  const readFile = relativePath => readSecureWorkspaceSkillFile(workspaceRoot, relativePath);
 
   for (const entry of entries) {
     if (entry.isSymbolicLink) continue;
     const relPath = subPath ? join(subPath, entry.name) : entry.name;
     const workspacePath = join(skillsRelativeRoot, relPath);
     if (entry.isFile && entry.name.endsWith('.md') && entry.name !== 'SKILL.md') {
-      const read = readWorkspaceFile(workspaceRoot, workspacePath, { maxBytes: MAX_PROJECT_SKILL_BYTES });
+      const read = readFile(workspacePath);
       if (!read || read.truncated) continue;
       const skill = parseSkill(read.buffer.toString('utf8'), entry.name);
       if (!skill?.name) {
@@ -370,13 +629,13 @@ function discoverWorkspaceSkills(workspaceRoot, skillsRelativeRoot, subPath = ''
     }
     if (!entry.isDirectory) continue;
 
-    const childEntries = listWorkspaceDirectory(workspaceRoot, workspacePath);
+    const childEntries = listSecureWorkspaceEntries(workspaceRoot, workspacePath);
     if (!childEntries) continue;
     const skillFile = childEntries.find(child => child.name === 'SKILL.md');
     if (skillFile) {
       if (!skillFile.isFile || skillFile.isSymbolicLink) continue;
       const skillRelativePath = join(workspacePath, 'SKILL.md');
-      const read = readWorkspaceFile(workspaceRoot, skillRelativePath, { maxBytes: MAX_PROJECT_SKILL_BYTES });
+      const read = readFile(skillRelativePath);
       if (!read || read.truncated) continue;
       const skill = parseSkill(read.buffer.toString('utf8'), entry.name);
       if (!skill?.name) {
@@ -646,7 +905,7 @@ export class SkillManager {
    * surfaced for historic YAML compatibility.
    *
    * @param {string} [_mode] — deprecated, ignored
-   * @returns {Array<{ name: string, description: string, trigger: string, mode: string, category?: string, platforms?: string[], keywords?: string[], source: string, tier?: string, hasReferences: boolean, hasTemplates: boolean }>}
+   * @returns {Array<{ name: string, description: string, trigger: string, mode: string, category?: string, platforms?: string[], keywords?: string[], source: string, tier?: string, managed: boolean, hasReferences: boolean, hasTemplates: boolean }>}
    */
   list(_mode) {
     const skills = [...this.#skills.values()];
@@ -661,11 +920,52 @@ export class SkillManager {
       keywords: s.keywords || undefined,
       source: s._source,
       tier: s._tier || undefined,
+      managed: (s._tier === 'user' || s._tier === 'project')
+        && this.#nativeRootsForTier(s._tier).some(root => isRemovableNativeSkill(s._path, root)),
       hasReferences: (s._references && s._references.length > 0) || false,
       hasTemplates: (s._templates && s._templates.length > 0) || false,
     }));
   }
 
+  #nativeRootsForTier(tier) {
+    return [...this.#tierByDir.entries()]
+      .filter(([, label]) => label === tier)
+      .map(([dir]) => dir);
+  }
+
+  /**
+   * Return every discovered Skill source, including lower-priority sources
+   * shadowed by an effective user or project override. Runtime callers keep
+   * using `list()`; this is strictly for management UIs that must not make a
+   * removable user Skill disappear just because a project overrides its name.
+   *
+   * @returns {Array<{ id: string, name: string, description: string, source: string, tier?: string, managed: boolean }>}
+   */
+  listSources() {
+    const sources = [];
+    for (const dir of this.#skillsDirs) {
+      const secure = this.#secureWorkspaceByDir.get(dir);
+      if (!secure && !existsSync(dir)) continue;
+      const { skills } = secure
+        ? discoverWorkspaceSkills(secure.workspaceRoot, secure.relativeRoot)
+        : discoverSkills(dir, '', { ignorePaths: this.#ignorePathsByDir.get(dir) || [] });
+      const tier = this.#tierByDir.get(dir) || basename(dir);
+      for (const skill of skills) {
+        if (!matchesPlatform(skill.platforms)) continue;
+        const path = skill._path || '';
+        sources.push({
+          id: `${tier}:${displaySkillPath(path)}`,
+          name: skill.name,
+          description: skill.description || '',
+          source: skill._source,
+          tier,
+          managed: (tier === 'user' || tier === 'project') && isRemovableNativeSkill(path, dir),
+        });
+      }
+    }
+    return sources;
+  }
+
   /**
    * View a skill's full content + linked files (progressive disclosure view tier).
    *
@@ -691,7 +991,7 @@ export class SkillManager {
           result.linkedContent = 'Error: path traversal not allowed';
         } else {
           const relativePath = join(skill._secureRelativePath, filePath);
-          const read = readWorkspaceFile(skill._secureWorkspaceRoot, relativePath, { maxBytes: MAX_PROJECT_SKILL_BYTES });
+          const read = readSecureWorkspaceSkillFile(skill._secureWorkspaceRoot, relativePath);
           result.linkedContent = !read
             ? 'Error reading file: secure workspace read failed'
             : (read.truncated ? 'Error reading file: linked file exceeds size limit' : read.buffer.toString('utf8'));

package/yeaft/web-bridge.js

@@ -17,14 +17,20 @@
 
 import { delimiter, join } from 'node:path';
 import { COLLAB_TOOL_POLICY } from './tools/registry.js';
-import { existsSync } from 'node:fs';
+import { existsSync, lstatSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { DEFAULT_YEAFT_DIR } from './init.js';
 import { buildDreamOutputSnapshot } from './dream/output-snapshot.js';
 import { Engine } from './engine.js';
 import { loadSession } from './session.js';
 import { loadAgentMCPConfig, loadConfig, loadMCPConfig } from './config.js';
-import { createSkillManager } from './skills.js';
+import {
+  createManagedProjectSkill,
+  createManagedSkill,
+  createSkillManager,
+  removeManagedProjectSkill,
+  removeManagedSkill,
+} from './skills.js';
 import { buildPluginCatalog, createPluginSkillManager, resolveMcpPluginPolicy } from './plugins.js';
 import { MCPManager } from './mcp.js';
 import { sendToServer } from '../connection/buffer.js';
@@ -53,7 +59,8 @@ import {
   migrateRegisteredWorkDirSessions,
   resolveSessionYeaftDir,
 } from './sessions/session-crud.js';
-import { openSession, loadSessionMeta } from './sessions/session-store.js';
+import { openSession, loadSessionMeta, SESSION_META_FILE } from './sessions/session-store.js';
+import { validateSessionId } from './sessions/ids.js';
 import { loadSessionConfig, normalizeSessionConfig, resolveSessionConfig, SessionConfigError } from './sessions/session-config.js';
 import { updateSessionConfig } from './sessions/session-crud.js';
 import { createCoordinator } from './sessions/coordinator.js';
@@ -3261,6 +3268,118 @@ function loadPluginCatalogMcpConfig(yeaftDir) {
   return loadAgentMCPConfig(yeaftDir);
 }
 
+const MANAGED_SKILL_SCOPES = new Set(['user', 'project']);
+
+function normalizedManagedSkillScope(value) {
+  const scope = typeof value === 'string' ? value.trim() : '';
+  return MANAGED_SKILL_SCOPES.has(scope) ? scope : '';
+}
+
+function resolveManagedSkillSession(yeaftDir, rawSessionId) {
+  const sessionId = typeof rawSessionId === 'string' ? rawSessionId.trim() : '';
+  const validation = validateSessionId(sessionId);
+  if (!validation.ok) throw new Error('invalid Session id');
+
+  // Skill mutation is a filesystem write. Its authority root is strictly the
+  // agent-local canonical store, not the read-compatible resolver: that one
+  // can consult bootstrap-only group-workdirs.json and project-local legacy
+  // Session directories. Those sources are not valid write authorization.
+  const sessionRoot = sessionsRoot(yeaftDir);
+  try {
+    const sessionRootStat = lstatSync(sessionRoot);
+    if (!sessionRootStat.isDirectory() || sessionRootStat.isSymbolicLink()) {
+      throw new Error('the selected Session was not found');
+    }
+  } catch (err) {
+    if (err?.message === 'the selected Session was not found') throw err;
+    throw new Error('the selected Session was not found');
+  }
+  const sessionDir = join(sessionRoot, sessionId);
+  // `loadSessionMeta()` deliberately supports legacy group.json for readers.
+  // This mutation path needs the canonical agent-local session.json instead.
+  const metaPath = join(sessionDir, SESSION_META_FILE);
+  if (!existsSync(metaPath)) throw new Error('the selected Session was not found');
+  try {
+    const sessionDirStat = lstatSync(sessionDir);
+    const metaStat = lstatSync(metaPath);
+    if (!sessionDirStat.isDirectory() || sessionDirStat.isSymbolicLink()
+      || !metaStat.isFile() || metaStat.isSymbolicLink()) {
+      throw new Error('the selected Session was not found');
+    }
+  } catch (err) {
+    if (err?.message === 'the selected Session was not found') throw err;
+    throw new Error('the selected Session was not found');
+  }
+  const meta = loadSessionMeta(sessionDir);
+  if (!meta || meta.id !== sessionId) throw new Error('the selected Session was not found');
+
+  const workDir = normalizeSessionWorkDir(meta.workDir);
+  if (!workDir) throw new Error('the selected Session has no project directory');
+  return { sessionId, workDir };
+}
+
+function currentRuntimeMatchesWorkDir(workDir) {
+  const runtime = activeSkillRuntime(captureRuntimeOwner());
+  return runtime && normalizeSessionWorkDir(runtime.workDir) === normalizeSessionWorkDir(workDir);
+}
+
+function reloadManagedSkillRuntime(scope, workDir = '') {
+  const owner = captureRuntimeOwner();
+  if (!owner) return;
+  if (scope === 'project' && currentRuntimeMatchesWorkDir(workDir)) {
+    reloadActiveSkills(owner);
+    return;
+  }
+  if (scope === 'user') reloadActiveSkills(owner);
+}
+
+function managedSkillCatalog(yeaftDir, workDir = '') {
+  const normalizedWorkDir = normalizeSessionWorkDir(workDir);
+  const runtime = resolvePluginCatalogRuntime(normalizedWorkDir);
+  const manager = createSkillManager(yeaftDir, normalizedWorkDir || process.cwd());
+  return buildPluginCatalog({ ...runtime, skillManager: manager });
+}
+
+/**
+ * Create or remove a native Yeaft Skill in an explicit user/project scope.
+ * The Session lookup is agent-local; browser-supplied filesystem paths are
+ * never trusted as a write target.
+ */
+export function handleYeaftManagedSkill(msg = {}) {
+  const requestId = msg.requestId || null;
+  const action = msg.action === 'remove' ? 'remove' : (msg.action === 'create' ? 'create' : '');
+  const scope = normalizedManagedSkillScope(msg.scope);
+  const sessionId = typeof msg.sessionId === 'string' ? msg.sessionId.trim() : '';
+  const yeaftDir = ctx.CONFIG?.yeaftDir || session?.yeaftDir || DEFAULT_YEAFT_DIR;
+  const respond = (payload) => sendToServer({
+    type: 'yeaft_managed_skill_result',
+    requestId,
+    ...(msg._requestClientId ? { _requestClientId: msg._requestClientId } : {}),
+    ...payload,
+  });
+  if (!action || !scope) {
+    respond({ catalog: { tools: [], skills: [], skillSources: [], mcpServers: [] }, error: 'skill action must be create or remove and scope must be user or project' });
+    return;
+  }
+  try {
+    const managedSession = scope === 'project'
+      ? resolveManagedSkillSession(yeaftDir, sessionId)
+      : null;
+    const result = scope === 'project'
+      ? (action === 'create'
+        ? createManagedProjectSkill(managedSession.workDir, msg.skill || {})
+        : removeManagedProjectSkill(managedSession.workDir, msg.name))
+      : (action === 'create'
+        ? createManagedSkill(join(yeaftDir, 'skills'), msg.skill || {})
+        : removeManagedSkill(join(yeaftDir, 'skills'), msg.name));
+    reloadManagedSkillRuntime(scope, managedSession?.workDir || '');
+    const catalog = managedSkillCatalog(yeaftDir, managedSession?.workDir || '');
+    respond({ scope, sessionId: managedSession?.sessionId || null, result, catalog, error: null });
+  } catch (err) {
+    respond({ scope, sessionId: null, catalog: { tools: [], skills: [], skillSources: [], mcpServers: [] }, error: err?.message || String(err) });
+  }
+}
+
 /** Test-only: read the MCP catalog source without sending a bridge response. */
 export function __testLoadPluginCatalogMcpConfig(yeaftDir) {
   return loadPluginCatalogMcpConfig(yeaftDir);