@openagents-org/agent-launcher 0.2.132 → 0.2.133

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.132",
+  "version": "0.2.133",
   "description": "OpenAgents Launcher — install, configure, and run AI coding agents from your terminal",
   "main": "src/index.js",
   "bin": {

package/src/adapters/base.js

@@ -230,9 +230,109 @@ class BaseAdapter {
       await this._postStatusReport(payload);
     } else if (action === 'routines') {
       await this._postRoutinesReport(payload);
+    } else if (action === 'skill.install') {
+      await this._handleSkillInstall(payload);
+    } else if (action === 'skill.uninstall') {
+      await this._handleSkillUninstall(payload);
     }
   }
 
+  /**
+   * Install a Skill Hub catalog skill into this agent's local skills
+   * directory, then report the result back to the workspace so the UI can
+   * show installing → installed / failed. Errors are logged loudly and
+   * surfaced as a `failed` status — never swallowed.
+   *
+   * payload: { action: "skill.install", skill: { id, name, source_repo, source_path } }
+   */
+  async _handleSkillInstall(payload) {
+    const installer = require('../skill-installer');
+    const skill = (payload && payload.skill) || null;
+    const skillId = skill && (skill.id || skill.skill_id);
+    if (!skillId) {
+      this._log('skill.install: missing skill metadata in payload — ignoring');
+      return;
+    }
+    this._log(`skill.install: starting install of "${skillId}" (type=${this.agentType}, dir=${this.workingDir || process.cwd()})`);
+
+    // Best-effort "installing" ping so the UI flips immediately even if the
+    // initial DB write from the request hasn't propagated to this client.
+    try {
+      await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
+        skillId, state: 'installing',
+      });
+    } catch (e) {
+      this._log(`skill.install: could not report 'installing' (non-fatal): ${e && e.message ? e.message : e}`);
+    }
+
+    try {
+      const result = installer.installSkill({
+        skill,
+        agentType: this.agentType,
+        workingDir: this.workingDir,
+        log: (m) => this._log(`skill.install: ${m}`),
+      });
+      try {
+        await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
+          skillId, state: 'installed', path: result.path, partial: result.partial === true,
+        });
+      } catch (e) {
+        this._log(`skill.install: installed on disk but failed to report 'installed': ${e && e.message ? e.message : e}`);
+      }
+      this._log(`skill.install: SUCCESS "${skillId}" → ${result.path}${result.partial ? ' (partial)' : ''}`);
+      await this._onSkillsChanged();
+    } catch (e) {
+      const msg = e && e.message ? e.message : String(e);
+      this._log(`skill.install: FAILED "${skillId}": ${msg}`);
+      try {
+        await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
+          skillId, state: 'failed', error: msg,
+        });
+      } catch (e2) {
+        this._log(`skill.install: also failed to report 'failed': ${e2 && e2.message ? e2.message : e2}`);
+      }
+    }
+  }
+
+  /**
+   * Remove a previously-installed skill from disk and report `uninstalled`.
+   */
+  async _handleSkillUninstall(payload) {
+    const installer = require('../skill-installer');
+    const skill = (payload && payload.skill) || null;
+    const skillId = skill && (skill.id || skill.skill_id);
+    if (!skillId) {
+      this._log('skill.uninstall: missing skill metadata in payload — ignoring');
+      return;
+    }
+    try {
+      const result = installer.uninstallSkill({
+        skill,
+        agentType: this.agentType,
+        workingDir: this.workingDir,
+        log: (m) => this._log(`skill.uninstall: ${m}`),
+      });
+      this._log(`skill.uninstall: "${skillId}" removed=${result.removed}`);
+      try {
+        await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
+          skillId, state: 'uninstalled',
+        });
+      } catch (e) {
+        this._log(`skill.uninstall: failed to report status: ${e && e.message ? e.message : e}`);
+      }
+      await this._onSkillsChanged();
+    } catch (e) {
+      const msg = e && e.message ? e.message : String(e);
+      this._log(`skill.uninstall: FAILED "${skillId}": ${msg}`);
+    }
+  }
+
+  /**
+   * Hook for subclasses to react to a change in the installed-skills set
+   * (e.g. rebuild prompt context). Default: no-op.
+   */
+  async _onSkillsChanged() {}
+
   /**
    * Post a chat message back to the requesting channel summarizing agent
    * name, type, agent-launcher version, uptime, and network. Used by the

package/src/adapters/codex.js

@@ -168,7 +168,7 @@ class CodexAdapter extends BaseAdapter {
   }
 
   _buildSystemContext(channelName) {
-    return buildOpenclawSystemPrompt({
+    const base = buildOpenclawSystemPrompt({
       agentName: this.agentName,
       workspaceId: this.workspaceId,
       channelName,
@@ -177,6 +177,38 @@ class CodexAdapter extends BaseAdapter {
       mode: this._mode,
       disabledModules: this.disabledModules,
     });
+    const skillsSection = this._buildInstalledSkillsSection();
+    return skillsSection ? `${base}\n\n${skillsSection}` : base;
+  }
+
+  /**
+   * Codex has no native skills-directory discovery (unlike Claude Code), so
+   * we inject installed Skill Hub skills directly into its context. Each
+   * skill's SKILL.md lives at <workingDir>/.codex/skills/<id>/SKILL.md and
+   * Codex (running with cwd=workingDir, full file access) can read it.
+   */
+  _buildInstalledSkillsSection() {
+    let skills = [];
+    try {
+      const installer = require('../skill-installer');
+      skills = installer.listInstalledSkills({
+        agentType: this.agentType || 'codex',
+        workingDir: this.workingDir,
+      });
+    } catch {
+      return '';
+    }
+    if (!skills.length) return '';
+    const lines = skills.map((s) => {
+      const desc = s.description ? ` — ${s.description}` : '';
+      return `- **${s.name}** (\`${s.id}\`)${desc}\n  Read its instructions: \`cat ${s.skillMd}\``;
+    });
+    return (
+      '## Installed Skills\n' +
+      'You have the following skills installed. When a task matches a skill, ' +
+      'read its `SKILL.md` (via the `cat` command shown) and follow it:\n' +
+      lines.join('\n')
+    );
   }
 
   // ------------------------------------------------------------------
@@ -205,14 +237,17 @@ class CodexAdapter extends BaseAdapter {
     } catch {}
   }
 
-  async _onControlAction(action, _payload) {
+  async _onControlAction(action, payload) {
     if (action === 'stop') {
       for (const [channel, proc] of Object.entries(this._channelProcesses)) {
         await this._stopProcess(proc);
         delete this._channelProcesses[channel];
         try { await this.sendStatus(channel, 'Execution stopped by user'); } catch {}
       }
+      return;
     }
+    // Shared actions (status, routines, skill.install, skill.uninstall).
+    await super._onControlAction(action, payload);
   }
 
   // ------------------------------------------------------------------

package/src/cli.js

@@ -128,6 +128,16 @@ async function cmdCreate(connector, flags, positional) {
     // Signal daemon to pick up the new agent
     try { connector.sendDaemonCommand('reload'); } catch {}
 
+    // Newly created agents are local-only until connected to a workspace.
+    // Without a workspace connection they will not appear in the Workspace Dashboard.
+    const created = connector.config.getAgent(name);
+    if (created && !created.network) {
+      print('');
+      print(`Note: '${name}' is local-only and will not appear in the Workspace Dashboard.`);
+      print(`To make it visible, connect it to a workspace:`);
+      print(`  agn connect ${name} <workspace-token>`);
+    }
+
     if (!connector.isInstalled(type)) {
       if (!flags.install) {
         print(`Runtime '${type}' is not installed. Run: agn install ${type}`);
@@ -278,9 +288,30 @@ async function cmdRuntimes(connector) {
 
 async function cmdConnect(connector, flags, positional) {
   const name = positional[0];
-  const token = positional[1] || flags.token;
-  if (!name || !token) {
+  // Token resolution order: positional arg / --token flag, then env vars.
+  // OPENAGENTS_WORKSPACE_TOKEN is preferred; OA_WORKSPACE_TOKEN is supported
+  // for compatibility with the existing mcp-server env var.
+  const token = positional[1]
+    || flags.token
+    || process.env.OPENAGENTS_WORKSPACE_TOKEN
+    || process.env.OA_WORKSPACE_TOKEN;
+
+  if (!name) {
     print('Usage: agn connect <agent-name> <token>');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!token) {
+    // No token supplied and none in the environment. Never prompt — keep
+    // CI / non-interactive environments from hanging. Print a helpful error
+    // explaining why the agent stays invisible and how to fix it.
+    print(`Error: no workspace token provided for '${name}'.`);
+    print(`Without a token, '${name}' stays local-only and will not appear in the Workspace Dashboard.`);
+    print('Provide a token in one of these ways:');
+    print(`  agn connect ${name} <workspace-token>`);
+    print(`  OPENAGENTS_WORKSPACE_TOKEN=<workspace-token> agn connect ${name}`);
+    process.exitCode = 1;
     return;
   }
 

package/src/installer.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execSync, exec } = require('child_process');
-const { whichBinary, getEnhancedEnv, getRuntimePrefix } = require('./paths');
+const { whichBinary, getEnhancedEnv, getRuntimePrefix, clearBinaryLookupCache } = require('./paths');
 const { EnvManager } = require('./env');
 
 const STATUS_CACHE_TTL_MS = 10000;
@@ -90,7 +90,15 @@ class Installer {
     // Fallback: check if binary exists on PATH (system install)
     const binaryPath = this._whichBinary(agentType);
     if (!binaryPath) {
-      try { fs.unlinkSync(path.join(this.markersDir, agentType)); } catch {}
+      // If a successful install wrote a marker, surface installed=true even
+      // when binary detection can't (yet) see the freshly-installed CLI —
+      // e.g. PATH caches not yet picking up a brand-new ~/.cursor/bin. The
+      // marker is the ground truth of what we just installed; UI was
+      // silently showing "not installed" right after a successful install
+      // because earlier code aggressively deleted the marker here.
+      if (this._hasMarker(agentType)) {
+        return { installed: true, managed: true, location: 'marker' };
+      }
       return { installed: false, managed: false, location: null };
     }
 
@@ -418,6 +426,8 @@ class Installer {
       cmd = rawCmd; // pip commands stay as-is
     }
 
+    cmd = this._wrapForWindowsShell(cmd);
+
     if (onData) onData(`$ ${cmd}\n\n`);
 
     const env = this._buildShellEnv();
@@ -579,6 +589,8 @@ class Installer {
       cmd = this._resolveNpmCommand(args);
     }
 
+    cmd = this._wrapForWindowsShell(cmd);
+
     if (onData) onData(`$ ${cmd}\n\n`);
 
     const env = this._buildShellEnv();
@@ -708,6 +720,12 @@ class Installer {
       fs.mkdirSync(this.markersDir, { recursive: true });
       fs.writeFileSync(path.join(this.markersDir, agentType), '', 'utf-8');
     } catch {}
+
+    // Drop the 30s PATH/whichBinary caches so the very next getInstallInfo
+    // sees the freshly-created bin dir (e.g. ~/.cursor/bin) instead of the
+    // pre-install snapshot. Without this, install completes but UI keeps
+    // showing "not installed" until the cache expires.
+    try { clearBinaryLookupCache(); } catch {}
   }
 
   _markUninstalled(agentType) {
@@ -727,6 +745,9 @@ class Installer {
       const markerFile = path.join(this.markersDir, agentType);
       if (fs.existsSync(markerFile)) fs.unlinkSync(markerFile);
     } catch {}
+
+    // Symmetric with _markInstalled: invalidate so detection re-runs cleanly.
+    try { clearBinaryLookupCache(); } catch {}
   }
 
   // -- Shell env + exec --
@@ -1040,6 +1061,24 @@ class Installer {
     return `${npmBin} ${args}`;
   }
 
+  /**
+   * Wrap a command in `powershell.exe -Command "..."` when (a) we're on Windows
+   * and (b) the command uses PowerShell-only tokens like `irm`, `iex`,
+   * `Invoke-RestMethod`, etc. The launcher's install shell is cmd.exe, which
+   * doesn't recognize these aliases — without wrapping, e.g. Cursor's
+   * `irm '…' | iex` exits 255. Skips commands already prefixed with
+   * `powershell`/`powershell.exe` so we don't double-wrap.
+   */
+  _wrapForWindowsShell(cmd) {
+    if (!cmd || process.platform !== 'win32') return cmd;
+    const trimmed = cmd.trimStart();
+    if (/^("[^"]*\\)?powershell(\.exe)?["']?\s/i.test(trimmed)) return cmd;
+    const psTokens = /\b(irm|iwr|iex|Invoke-RestMethod|Invoke-WebRequest|Invoke-Expression|Expand-Archive|Get-[A-Z]\w*|Set-[A-Z]\w*)\b/;
+    if (!psTokens.test(cmd)) return cmd;
+    const escaped = cmd.replace(/"/g, '\\"');
+    return `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "${escaped}"`;
+  }
+
   _execShell(cmd, timeoutMs = 300000) {
     return new Promise((resolve, reject) => {
       const env = this._buildShellEnv();
@@ -1049,7 +1088,8 @@ class Installer {
         shell = env.ComSpec || 'C:\\Windows\\System32\\cmd.exe';
       }
 
-      exec(cmd, {
+      const finalCmd = this._wrapForWindowsShell(cmd);
+      exec(finalCmd, {
         encoding: 'utf-8',
         timeout: timeoutMs,
         shell,

package/src/paths.js

@@ -264,6 +264,9 @@ function _addUnixPaths(dirs) {
 
   // cargo
   _push(dirs, path.join(HOME, '.cargo', 'bin'));
+
+  // Cursor CLI native installer (curl https://cursor.com/install | bash)
+  _push(dirs, path.join(HOME, '.cursor', 'bin'));
 }
 
 // ---- macOS-specific ----
@@ -336,11 +339,23 @@ function getCorePrefix() {
   return path.join(HOME, '.openagents', 'core');
 }
 
+/**
+ * Reset the two 30s caches that back binary detection. Call this after
+ * install / uninstall so a freshly-created bin dir (e.g. ~/.cursor/bin)
+ * isn't masked by a pre-install snapshot of getExtraBinDirs(), and so a
+ * `whichBinary(name) === null` cached before install doesn't survive.
+ */
+function clearBinaryLookupCache() {
+  extraBinDirsCache = { value: null, at: 0, path: '' };
+  whichBinaryCache.clear();
+}
+
 module.exports = {
   getExtraBinDirs,
   getEnhancedPATH,
   getEnhancedEnv,
   whichBinary,
+  clearBinaryLookupCache,
   getRuntimePrefix,
   getCorePrefix,
   IS_WINDOWS,

package/src/skill-installer.js

@@ -0,0 +1,382 @@
+'use strict';
+
+/**
+ * Skill installer — installs third-party Agent Skills (Skill Hub catalog
+ * entries) into a local agent's skills directory.
+ *
+ * Responsibilities (all independently testable):
+ *  - Resolve the per-agent-type skills directory.
+ *  - Fetch the skill's files from its source repo into that directory.
+ *  - Verify a SKILL.md actually landed (no silent success).
+ *  - Enumerate already-installed skills (used to inject context for agents,
+ *    like Codex, that don't auto-discover a skills directory).
+ *
+ * The "how bytes arrive" step is injected via a `fetcher` so production can
+ * use git/https while tests use a local fixture copier. The directory
+ * resolution, file verification, and error handling — the parts that decide
+ * end-to-end correctness — are exercised directly.
+ *
+ * A catalog skill is identified by `source_repo` + `source_path`
+ * (e.g. "anthropics/skills" + "skills/claude-api"), mirroring the Skill Hub
+ * catalog in workspace/backend/app/skill_catalog.py.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Resolve the skills directory for a given agent type, rooted at the agent's
+ * working directory. Different runtimes look in different places:
+ *  - claude  → <workingDir>/.claude/skills   (Claude Code auto-discovers here)
+ *  - cursor  → <workingDir>/.cursor/skills   (Cursor auto-discovers here)
+ *  - codex   → <workingDir>/.codex/skills    (no native discovery; the Codex
+ *              adapter injects these into the prompt — see codex.js)
+ *  - default → <workingDir>/.agent/skills
+ *
+ * @param {string} agentType
+ * @param {string} [workingDir]
+ * @returns {string} absolute path to the skills directory
+ */
+function skillsDirForAgentType(agentType, workingDir) {
+  const base = workingDir || process.cwd();
+  switch ((agentType || '').toLowerCase()) {
+    case 'claude':
+      return path.join(base, '.claude', 'skills');
+    case 'cursor':
+      return path.join(base, '.cursor', 'skills');
+    case 'codex':
+      return path.join(base, '.codex', 'skills');
+    default:
+      return path.join(base, '.agent', 'skills');
+  }
+}
+
+/**
+ * Normalize a catalog skill object (snake_case from backend / camelCase from
+ * UI) to a stable shape.
+ */
+// Validation patterns. The skill metadata comes from a workspace.agent.control
+// event, which any holder of the workspace token could craft — so the launcher
+// does NOT trust it blindly even though the backend only emits catalog entries.
+// These guards prevent path traversal (a malicious id/source_path escaping the
+// skills dir) and argument injection (a value starting with "-" being read as a
+// git/curl flag).
+const _ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;          // no leading dash, no slashes/dots-only
+const _REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;  // owner/repo
+const _PATH_SEG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;    // each path segment
+
+function _assertSafeId(id) {
+  if (typeof id !== 'string' || id === '.' || id === '..' || !_ID_RE.test(id)) {
+    throw new Error(`unsafe skill id "${id}" (must match ${_ID_RE})`);
+  }
+}
+
+function _assertSafeSourceRepo(repo) {
+  if (repo && !_REPO_RE.test(repo)) {
+    throw new Error(`unsafe source_repo "${repo}" (expected owner/repo)`);
+  }
+}
+
+function _assertSafeSourcePath(sp) {
+  if (!sp) return;
+  const segs = sp.replace(/^\/+|\/+$/g, '').split('/');
+  for (const seg of segs) {
+    if (seg === '..' || !_PATH_SEG_RE.test(seg)) {
+      throw new Error(`unsafe source_path "${sp}" (segment "${seg}")`);
+    }
+  }
+}
+
+function normalizeSkill(skill) {
+  if (!skill || typeof skill !== 'object') {
+    throw new Error('skill metadata missing');
+  }
+  const id = skill.id || skill.skill_id || skill.skillId;
+  if (!id) throw new Error('skill metadata missing id');
+  _assertSafeId(id);
+  const sourceRepo = skill.source_repo || skill.sourceRepo || '';
+  const sourcePath = skill.source_path || skill.sourcePath || '';
+  _assertSafeSourceRepo(sourceRepo);
+  _assertSafeSourcePath(sourcePath);
+  return {
+    id,
+    name: skill.name || id,
+    description: skill.description || '',
+    sourceRepo,
+    sourcePath,
+  };
+}
+
+/**
+ * Resolve <skillsDir>/<id> and assert it stays inside <skillsDir>. Belt-and-
+ * suspenders on top of _assertSafeId so we never read/write/delete outside the
+ * agent's skills directory.
+ */
+function _safeSkillDir(skillsDir, id) {
+  const dest = path.resolve(skillsDir, id);
+  const root = path.resolve(skillsDir);
+  if (dest !== path.join(root, id) || !dest.startsWith(root + path.sep)) {
+    throw new Error(`refusing to operate on "${dest}" outside skills dir "${root}"`);
+  }
+  return dest;
+}
+
+/**
+ * Default fetcher: download the skill's files from GitHub into `destDir`.
+ *
+ * Strategy, in order of preference:
+ *   1. git sparse-checkout of `<source_repo>` limited to `<source_path>`
+ *      (gets the full skill directory — scripts, references, assets).
+ *   2. Fallback: fetch just `SKILL.md` over HTTPS from raw.githubusercontent.
+ *
+ * Throws if neither strategy produces a SKILL.md. Never silently no-ops.
+ *
+ * @param {{skill: object, destDir: string, log?: function}} args
+ */
+function defaultFetcher({ skill, destDir, log }) {
+  const { sourceRepo, sourcePath } = skill;
+  if (!sourceRepo) {
+    throw new Error(`skill "${skill.id}" has no source_repo; cannot fetch`);
+  }
+  const _log = log || (() => {});
+
+  // ── Strategy 1: git sparse-checkout ──
+  if (_gitAvailable()) {
+    let tmp;
+    try {
+      tmp = fs.mkdtempSync(path.join(os.tmpdir(), `skill-${skill.id}-`));
+      const repoUrl = `https://github.com/${sourceRepo}.git`;
+      const sp = sourcePath || '.';
+      execFileSync('git', ['clone', '--depth', '1', '--filter=blob:none', '--sparse', repoUrl, tmp],
+        { stdio: 'pipe', timeout: 120000 });
+      execFileSync('git', ['-C', tmp, 'sparse-checkout', 'set', sp],
+        { stdio: 'pipe', timeout: 60000 });
+      const srcDir = path.join(tmp, sp);
+      if (!fs.existsSync(srcDir)) {
+        throw new Error(`source path "${sp}" not found in ${sourceRepo}`);
+      }
+      _copyDir(srcDir, destDir);
+      _log(`Fetched ${sourceRepo}/${sp} via git sparse-checkout`);
+      return { partial: false };
+    } catch (e) {
+      _log(`git fetch failed (${e && e.message ? e.message : e}); trying raw SKILL.md`);
+    } finally {
+      if (tmp) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {} }
+    }
+  }
+
+  // ── Strategy 2: raw SKILL.md over HTTPS ──
+  const sp = (sourcePath || '').replace(/^\/+|\/+$/g, '');
+  for (const branch of ['main', 'master']) {
+    const rawUrl = `https://raw.githubusercontent.com/${sourceRepo}/${branch}/${sp ? sp + '/' : ''}SKILL.md`;
+    try {
+      const body = _httpGetSync(rawUrl);
+      if (body && body.trim()) {
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.writeFileSync(path.join(destDir, 'SKILL.md'), body, 'utf-8');
+        _log(`Fetched SKILL.md via HTTPS (${branch})`);
+        // Only the SKILL.md was retrieved — any bundled scripts/references the
+        // skill ships were NOT fetched. Signal "partial" so installSkill can
+        // warn; skills that depend on those files may not be fully functional.
+        return { partial: true };
+      }
+    } catch {
+      // try next branch
+    }
+  }
+
+  throw new Error(`could not fetch skill "${skill.id}" from ${sourceRepo}/${sourcePath}`);
+}
+
+/**
+ * Install a catalog skill into the agent's skills directory.
+ *
+ * @param {object} args
+ * @param {object} args.skill        catalog entry (id, name, source_repo, source_path)
+ * @param {string} args.agentType    e.g. "claude", "codex"
+ * @param {string} [args.workingDir] agent working dir; defaults to cwd
+ * @param {function} [args.fetcher]  ({skill, destDir, log}) => void; defaults to git/https
+ * @param {function} [args.log]
+ * @returns {{path: string, skillId: string}}
+ * @throws {Error} with a clear, surfaceable message on any failure
+ */
+function installSkill({ skill, agentType, workingDir, fetcher, log }) {
+  const norm = normalizeSkill(skill);
+  const _log = log || (() => {});
+  const skillsDir = skillsDirForAgentType(agentType, workingDir);
+  const destDir = _safeSkillDir(skillsDir, norm.id);
+
+  // Ensure the parent skills directory exists / is writable. A clear error
+  // here distinguishes "no permission / bad working dir" from fetch failures.
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch (e) {
+    throw new Error(
+      `cannot create skills directory "${destDir}" for agent type "${agentType}": ` +
+      `${e && e.message ? e.message : e}`
+    );
+  }
+
+  // Re-installing: start clean so stale files from a prior version don't linger.
+  try {
+    for (const entry of fs.readdirSync(destDir)) {
+      fs.rmSync(path.join(destDir, entry), { recursive: true, force: true });
+    }
+  } catch {}
+
+  const doFetch = fetcher || defaultFetcher;
+  const fetchResult = doFetch({ skill: norm, destDir, log: _log }) || {};
+
+  // No silent success: a real install must produce a SKILL.md.
+  const skillMd = _findSkillMd(destDir);
+  if (!skillMd) {
+    throw new Error(
+      `install of "${norm.id}" produced no SKILL.md in ${destDir} ` +
+      `(fetched from ${norm.sourceRepo}/${norm.sourcePath})`
+    );
+  }
+
+  // A partial fetch (SKILL.md only, bundled scripts/references missing) is a
+  // known degraded state — succeed but WARN loudly so it isn't mistaken for a
+  // fully-functional install.
+  const partial = fetchResult.partial === true;
+  if (partial) {
+    _log(
+      `WARNING: only SKILL.md was fetched for "${norm.id}" — bundled files ` +
+      `(scripts/references) were NOT installed; skills that need them may not work fully`
+    );
+  }
+
+  _log(`Installed skill "${norm.id}" → ${destDir}${partial ? ' (partial: SKILL.md only)' : ''}`);
+  return { path: destDir, skillId: norm.id, partial };
+}
+
+/**
+ * Remove an installed skill directory. Idempotent.
+ *
+ * @returns {{path: string, removed: boolean, skillId: string}}
+ */
+function uninstallSkill({ skill, agentType, workingDir, log }) {
+  const norm = normalizeSkill(skill);
+  const _log = log || (() => {});
+  const destDir = _safeSkillDir(skillsDirForAgentType(agentType, workingDir), norm.id);
+  let removed = false;
+  if (fs.existsSync(destDir)) {
+    fs.rmSync(destDir, { recursive: true, force: true });
+    removed = true;
+    _log(`Uninstalled skill "${norm.id}" from ${destDir}`);
+  }
+  return { path: destDir, removed, skillId: norm.id };
+}
+
+/**
+ * Enumerate installed third-party skills under the agent's skills directory.
+ * Each returned entry parses the SKILL.md frontmatter for name/description.
+ * Used by adapters (e.g. Codex) that must inject skill availability into the
+ * model context because the runtime doesn't auto-discover skills.
+ *
+ * @returns {Array<{id: string, name: string, description: string, path: string, skillMd: string}>}
+ */
+function listInstalledSkills({ agentType, workingDir }) {
+  const skillsDir = skillsDirForAgentType(agentType, workingDir);
+  let entries;
+  try {
+    entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const dir = path.join(skillsDir, ent.name);
+    const skillMd = _findSkillMd(dir);
+    if (!skillMd) continue;
+    const meta = _parseSkillFrontmatter(skillMd);
+    out.push({
+      id: ent.name,
+      name: meta.name || ent.name,
+      description: meta.description || '',
+      path: dir,
+      skillMd,
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function _gitAvailable() {
+  try {
+    execFileSync('git', ['--version'], { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function _findSkillMd(dir) {
+  // Prefer a top-level SKILL.md; fall back to any *.md so single-file skills
+  // (e.g. fetched as openagents-workspace.md) still count as installed.
+  const candidates = ['SKILL.md', 'skill.md', 'Skill.md'];
+  for (const c of candidates) {
+    const p = path.join(dir, c);
+    if (fs.existsSync(p)) return p;
+  }
+  try {
+    const md = fs.readdirSync(dir).find((f) => f.toLowerCase().endsWith('.md'));
+    if (md) return path.join(dir, md);
+  } catch {}
+  return null;
+}
+
+function _parseSkillFrontmatter(skillMdPath) {
+  try {
+    const text = fs.readFileSync(skillMdPath, 'utf-8');
+    const m = text.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!m) return {};
+    const out = {};
+    for (const line of m[1].split('\n')) {
+      const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+      if (kv) out[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function _copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const ent of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, ent.name);
+    const d = path.join(dest, ent.name);
+    if (ent.isDirectory()) _copyDir(s, d);
+    else if (ent.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
+// Blocking GET used only by defaultFetcher's HTTPS fallback (which runs off
+// the hot path inside a try/catch). Uses curl for redirect handling; returns
+// the body string or throws. git sparse-checkout is the primary strategy, so
+// this only matters on hosts that have curl but not git.
+function _httpGetSync(url) {
+  try {
+    const body = execFileSync('curl', ['-fsSL', url], { timeout: 60000, maxBuffer: 10 * 1024 * 1024 });
+    return body.toString('utf-8');
+  } catch (e) {
+    throw new Error(`HTTPS fetch failed for ${url}: ${e && e.message ? e.message : e}`);
+  }
+}
+
+module.exports = {
+  skillsDirForAgentType,
+  installSkill,
+  uninstallSkill,
+  listInstalledSkills,
+  normalizeSkill,
+  defaultFetcher,
+};

package/src/workspace-client.js

@@ -357,6 +357,30 @@ class WorkspaceClient {
     }
   }
 
+  /**
+   * Report skill-install progress/result back to the workspace.
+   *
+   * POST /v1/workspaces/{id}/members/{agentName}/skills/status
+   * Body: { skill_id, state: "installing"|"installed"|"failed"|"uninstalled",
+   *         path?, error? }
+   *
+   * The backend updates WorkspaceMember.enabled_skills.skill_status so the
+   * Skill Hub UI can render installing / installed / failed states. Best
+   * effort — returns the updated payload or throws (caller decides).
+   */
+  async reportSkillStatus(workspaceId, agentName, token, { skillId, state, path: installPath, error, partial } = {}) {
+    const body = { skill_id: skillId, state };
+    if (installPath) body.path = installPath;
+    if (error) body.error = String(error).slice(0, 2000);
+    if (partial) body.partial = true;
+    const data = await this._post(
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(agentName)}/skills/status`,
+      body,
+      this._wsHeaders(token),
+    );
+    return data.data || data;
+  }
+
   /**
    * Get session/channel info via GET /v1/workspaces/{id}/channels/{name}.
    */