llm-cli-gateway 2.14.1 → 2.15.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to the llm-cli-gateway project.
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-07-03
+
+### Added
+
+- **Updateable local skill packs.** Gateway startup now loads bundled skills,
+  optional `[skills].paths`, `LLM_GATEWAY_SKILLS_PATH`, and
+  `~/.llm-cli-gateway/skills` with deterministic override precedence. Skill
+  pack roots can include a `skill-pack.json` integrity manifest that pins each
+  loaded `SKILL.md` by SHA-256, allowing operators to update workflow skills
+  outside core gateway npm releases without silent network fetches.
+
 ## [2.14.1] - 2026-07-03
 
 ### Added

package/README.md

@@ -53,6 +53,40 @@ Or use directly with `npx` from an MCP client:
 
 The repo ships agent-ready workflow skills under [`.agents/skills`](.agents/skills) for async orchestration, session continuity, multi-LLM review, implement-review-fix loops, retrospective evidence walks, and secure approval-gated dispatch. Seven caller-facing skills are bundled in the published npm package: `async-job-orchestration`, `multi-llm-review`, `session-workflow`, `secure-orchestration`, `implement-review-fix`, `retrospective-walk`, and `public-demo-session`. Machine-readable DAG-TOML plans live under [`docs/plans`](docs/plans) and [`setup/install-plan.dag.toml`](setup/install-plan.dag.toml) for workflows that need deterministic sequencing and verification gates.
 
+Skill packs can be updated outside the core npm release by placing skill
+directories in local, operator-controlled paths. The gateway loads bundled
+skills first, then `[skills].paths`, then `LLM_GATEWAY_SKILLS_PATH`, then
+`~/.llm-cli-gateway/skills` when it exists; later roots override earlier skills
+by name. Each skill is a directory containing `SKILL.md`. A root may also carry
+`skill-pack.json` to pin expected `SKILL.md` hashes:
+
+```toml
+[skills]
+paths = ["/opt/llm-cli-gateway/skills"]
+```
+
+```bash
+export LLM_GATEWAY_SKILLS_PATH="/opt/team-skill-pack:/opt/incident-skill-pack"
+```
+
+```json
+{
+  "name": "team-pack",
+  "version": "1.0.0",
+  "skills": [
+    {
+      "name": "incident-retrospective",
+      "sha256": "<sha256 of incident-retrospective/SKILL.md>"
+    }
+  ]
+}
+```
+
+The loader is intentionally local-only: it never fetches remote Markdown at
+startup. To update a pack, install or replace files through your package manager
+or deployment system, then restart the gateway so the advertised `skills://...`
+resources refresh.
+
 The next documentation focus is provider-specific skill and DAG-TOML pairs for each outbound CLI and API-provider family: Claude, Codex, Gemini/Antigravity, Grok, Mistral Vibe, Devin, Cursor Agent, OpenAI-compatible endpoints, Anthropic Messages, and xAI Responses. The implementation plan is tracked in [`docs/plans/provider-workflow-assets.dag.toml`](docs/plans/provider-workflow-assets.dag.toml), with each provider asset expected to cover install/login checks or token-env checks, session behavior, approval modes, cache/telemetry surfaces, failure modes, and a smoke-test gate.
 
 ## Trust & Supply Chain
@@ -1435,6 +1469,7 @@ await callTool("session_delete", {
   LLM_GATEWAY_OAUTH_REQUIRE_CONSENT=1 LLM_GATEWAY_OAUTH_CONSENT_SECRET='choose-a-strong-code' node dist/index.js
   ```
 - `LLM_GATEWAY_CONFIG`: Path to the gateway TOML config (default: `~/.llm-cli-gateway/config.toml`). See **Persistence configuration** above for the `[persistence]` schema.
+- `LLM_GATEWAY_SKILLS_PATH`: Extra local skill-pack roots to load at startup, separated by the host path delimiter (`:` on Linux/macOS, `;` on Windows). These paths are appended after `[skills].paths`; `~/.llm-cli-gateway/skills` still loads last when present.
 - `LLM_GATEWAY_LOGS_DB`: **Deprecated** — overrides `[persistence].path` and selects `backend = "sqlite"` (or `backend = "none"` when set to `none`). Emits a deprecation warning at startup; migrate to `config.toml`.
   ```bash
   # Custom path

package/dist/config.d.ts

@@ -15,6 +15,13 @@ export interface Config {
     database?: DatabaseConfig;
     sessionTtl: number;
 }
+export interface SkillsConfig {
+    paths: string[];
+    sources: {
+        configFile: string | null;
+        envOverrides: string[];
+    };
+}
 export declare function loadConfig(): Config;
 export declare const PERSISTENCE_BACKENDS: readonly ["sqlite", "postgres", "memory", "none"];
 export type PersistenceBackend = (typeof PERSISTENCE_BACKENDS)[number];
@@ -46,6 +53,7 @@ export interface PersistenceConfigSources {
     envOverrides: string[];
 }
 export declare function defaultGatewayConfigPath(): string;
+export declare function loadSkillsConfig(logger?: Logger): SkillsConfig;
 export declare function loadPersistenceConfig(logger?: Logger): PersistenceConfig;
 export declare const DEFAULT_HTTP_MAX_SESSIONS = 100;
 export declare const DEFAULT_HTTP_SESSION_IDLE_TTL_MS: number;

package/dist/config.js

@@ -14,6 +14,12 @@ const DatabaseUrlSchema = z
     message: "Database URL must start with postgresql:// or postgres://",
 });
 export const DEFAULT_SESSION_TTL_SECONDS = 2592000;
+const SkillsSchema = z
+    .object({
+    paths: z.array(z.string().min(1)).default([]),
+})
+    .strict()
+    .default({ paths: [] });
 export function loadConfig() {
     const databaseUrl = process.env.DATABASE_URL;
     const rawSessionTtl = parseInt(process.env.SESSION_TTL || String(DEFAULT_SESSION_TTL_SECONDS), 10);
@@ -89,6 +95,32 @@ function defaultPersistenceConfigPath() {
 export function defaultGatewayConfigPath() {
     return defaultPersistenceConfigPath();
 }
+export function loadSkillsConfig(logger = noopLogger) {
+    const configPath = defaultGatewayConfigPath();
+    const { parsed, sourcePath } = readGatewayTomlFile(configPath, logger, "skills");
+    const rawSkills = parsed?.skills ?? {};
+    const sources = {
+        configFile: sourcePath,
+        envOverrides: [],
+    };
+    let skillsParsed;
+    try {
+        skillsParsed = SkillsSchema.parse(rawSkills);
+    }
+    catch (err) {
+        throw new Error(`Invalid [skills] config: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const paths = [...skillsParsed.paths];
+    const envPaths = process.env.LLM_GATEWAY_SKILLS_PATH;
+    if (envPaths !== undefined && envPaths.trim().length > 0) {
+        paths.push(...envPaths
+            .split(path.delimiter)
+            .map(part => part.trim())
+            .filter(Boolean));
+        sources.envOverrides.push("LLM_GATEWAY_SKILLS_PATH");
+    }
+    return { paths, sources };
+}
 function readPersistenceFile(configPath, logger) {
     if (!existsSync(configPath)) {
         return { raw: undefined, sourcePath: null };

package/dist/index.js

@@ -3,7 +3,7 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { randomUUID } from "crypto";
 import { createRequire } from "module";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, chmodSync, } from "fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, chmodSync, } from "fs";
 import { basename, dirname, isAbsolute, join, relative } from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod/v3";
@@ -21,7 +21,8 @@ import { ResourceProvider } from "./resources.js";
 import { generateResourceDescriptors, generateProviderAcpDescriptors, } from "./provider-surface-generator.js";
 import { PerformanceMetrics } from "./metrics.js";
 import { estimateTokens, optimizePrompt as optimizePromptText, optimizeResponse as optimizeResponseText, } from "./optimizer.js";
-import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvidersConfig, loadAcpConfig, loadAdminConfig, loadLimitsConfig, defaultGatewayConfigPath, isXaiProviderEnabled, enabledApiProviders, minStableTokensForModel, } from "./config.js";
+import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvidersConfig, loadAcpConfig, loadAdminConfig, loadLimitsConfig, loadSkillsConfig, defaultGatewayConfigPath, isXaiProviderEnabled, enabledApiProviders, minStableTokensForModel, } from "./config.js";
+import { loadGatewaySkills } from "./skill-loader.js";
 import { runAcpRequest } from "./acp/runtime.js";
 import { isAcpError } from "./acp/errors.js";
 import { redactSecrets } from "./secret-redaction.js";
@@ -184,27 +185,13 @@ function packageVersion() {
     }
     return "unknown";
 }
-function loadSkills() {
-    const skills = [];
-    try {
-        const dirs = readdirSync(SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory());
-        for (const dir of dirs) {
-            const skillPath = join(SKILLS_DIR, dir.name, "SKILL.md");
-            try {
-                const content = readFileSync(skillPath, "utf-8");
-                const descMatch = content.match(/^---[\s\S]*?description:\s*(.+?)$/m);
-                const description = descMatch?.[1]?.trim() || dir.name;
-                skills.push({ name: dir.name, content, description });
-            }
-            catch {
-            }
-        }
-    }
-    catch {
-    }
-    return skills;
-}
-const loadedSkills = loadSkills();
+const skillsConfig = loadSkillsConfig(logger);
+const loadedSkills = loadGatewaySkills({
+    bundledSkillsDir: SKILLS_DIR,
+    configuredPaths: skillsConfig.paths,
+    envSkillsPath: undefined,
+    logger,
+});
 export function buildServerInstructions(asyncJobsEnabled, grokApiToolsEnabled = false) {
     const asyncToolsNote = asyncJobsEnabled ? " | *_request_async (async)" : "";
     const apiToolsNote = grokApiToolsEnabled ? ", grok_api_request" : "";

package/dist/skill-loader.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from "./logger.js";
+export interface SkillEntry {
+    name: string;
+    content: string;
+    description: string;
+    source: "bundled" | "external";
+    path: string;
+    pack: {
+        name: string;
+        version: string;
+        manifestPath: string;
+        verified: boolean;
+    } | null;
+}
+export interface LoadGatewaySkillsOptions {
+    bundledSkillsDir: string;
+    configuredPaths?: string[];
+    envSkillsPath?: string | undefined;
+    userSkillsDir?: string;
+    logger?: Logger;
+}
+export declare function defaultUserSkillsDir(): string;
+export declare function parseSkillPathList(raw: string | undefined): string[];
+export declare function loadGatewaySkills(options: LoadGatewaySkillsOptions): SkillEntry[];

package/dist/skill-loader.js

@@ -0,0 +1,201 @@
+import { createHash } from "crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+import { z } from "zod/v3";
+import { logWarn, noopLogger } from "./logger.js";
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const SkillPackManifestSchema = z
+    .object({
+    name: z.string().regex(SKILL_NAME_PATTERN),
+    version: z.string().min(1),
+    skills: z
+        .array(z
+        .object({
+        name: z.string().regex(SKILL_NAME_PATTERN),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/i),
+    })
+        .strict())
+        .default([]),
+})
+    .strict();
+export function defaultUserSkillsDir() {
+    return path.join(homedir(), ".llm-cli-gateway", "skills");
+}
+export function parseSkillPathList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(path.delimiter)
+        .map(part => part.trim())
+        .filter(Boolean);
+}
+export function loadGatewaySkills(options) {
+    const logger = options.logger ?? noopLogger;
+    const roots = [
+        { path: options.bundledSkillsDir, source: "bundled", label: "bundled" },
+        ...normalizeExternalRoots(options.configuredPaths ?? [], "configured"),
+        ...normalizeExternalRoots(parseSkillPathList(options.envSkillsPath), "LLM_GATEWAY_SKILLS_PATH"),
+    ];
+    const userSkillsDir = options.userSkillsDir ?? defaultUserSkillsDir();
+    if (existsSync(userSkillsDir)) {
+        roots.push({ path: userSkillsDir, source: "external", label: "user" });
+    }
+    const byName = new Map();
+    for (const root of roots) {
+        for (const skill of readSkillRoot(root, logger)) {
+            const prior = byName.get(skill.name);
+            if (prior) {
+                logWarn(logger, `Skill '${skill.name}' from ${skill.path} overrides ${prior.source} skill at ${prior.path}`);
+            }
+            byName.set(skill.name, skill);
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function normalizeExternalRoots(paths, label) {
+    return paths.map(p => ({
+        path: expandHome(p),
+        source: "external",
+        label,
+    }));
+}
+function expandHome(p) {
+    return p === "~" ? homedir() : p.startsWith("~/") ? path.join(homedir(), p.slice(2)) : p;
+}
+function readSkillRoot(root, logger) {
+    if (!existsSync(root.path)) {
+        if (root.source === "external") {
+            logWarn(logger, `Configured skill path does not exist; skipping: ${root.path}`);
+        }
+        return [];
+    }
+    let stat;
+    try {
+        stat = statSync(root.path);
+    }
+    catch (err) {
+        logWarn(logger, `Cannot stat skill path; skipping: ${root.path}`, err);
+        return [];
+    }
+    if (!stat.isDirectory()) {
+        logWarn(logger, `Skill path is not a directory; skipping: ${root.path}`);
+        return [];
+    }
+    const manifest = readManifest(root, logger);
+    if (manifest === "invalid")
+        return [];
+    if (existsSync(path.join(root.path, "SKILL.md"))) {
+        const skill = readSkillDir(root.path, root, manifest, logger);
+        return skill ? [skill] : [];
+    }
+    let entries;
+    try {
+        entries = readdirSync(root.path, { withFileTypes: true });
+    }
+    catch (err) {
+        logWarn(logger, `Cannot read skill path; skipping: ${root.path}`, err);
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skill = readSkillDir(path.join(root.path, entry.name), root, manifest, logger);
+        if (skill)
+            skills.push(skill);
+    }
+    if (manifest && manifest.skills.length > 0) {
+        const loaded = new Set(skills.map(skill => skill.name));
+        for (const expected of manifest.skills) {
+            if (!loaded.has(expected.name)) {
+                logWarn(logger, `Skill pack '${manifest.name}' declares '${expected.name}', but no verified SKILL.md was loaded`);
+            }
+        }
+    }
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+function readManifest(root, logger) {
+    const manifestPath = path.join(root.path, "skill-pack.json");
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return SkillPackManifestSchema.parse(raw);
+    }
+    catch (err) {
+        logWarn(logger, `Invalid skill-pack.json at ${manifestPath}; skipping skill pack`, err);
+        return "invalid";
+    }
+}
+function readSkillDir(skillDir, root, manifest, logger) {
+    const skillPath = path.join(skillDir, "SKILL.md");
+    if (!existsSync(skillPath))
+        return null;
+    let content;
+    try {
+        content = readFileSync(skillPath, "utf8");
+    }
+    catch (err) {
+        logWarn(logger, `Cannot read skill file; skipping: ${skillPath}`, err);
+        return null;
+    }
+    const frontmatter = parseSkillFrontmatter(content);
+    const dirName = path.basename(skillDir);
+    const name = frontmatter.name || dirName;
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        logWarn(logger, `Invalid skill name '${name}' in ${skillPath}; skipping`);
+        return null;
+    }
+    if (frontmatter.name && frontmatter.name !== dirName) {
+        logWarn(logger, `Skill frontmatter name '${frontmatter.name}' does not match directory '${dirName}'; skipping ${skillPath}`);
+        return null;
+    }
+    const packInfo = verifyManifestEntry(name, content, skillPath, root, manifest, logger);
+    if (packInfo === "skip")
+        return null;
+    return {
+        name,
+        content,
+        description: frontmatter.description || name,
+        source: root.source,
+        path: skillPath,
+        pack: packInfo,
+    };
+}
+function verifyManifestEntry(name, content, skillPath, root, manifest, logger) {
+    if (!manifest)
+        return null;
+    const expected = manifest.skills.find(skill => skill.name === name);
+    if (!expected) {
+        logWarn(logger, `Skill pack '${manifest.name}' does not list '${name}' in skill-pack.json; skipping ${skillPath}`);
+        return "skip";
+    }
+    const actual = createHash("sha256").update(content, "utf8").digest("hex");
+    if (actual.toLowerCase() !== expected.sha256.toLowerCase()) {
+        logWarn(logger, `Skill pack '${manifest.name}' hash mismatch for '${name}'; skipping ${skillPath}`);
+        return "skip";
+    }
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        manifestPath: path.join(root.path, "skill-pack.json"),
+        verified: true,
+    };
+}
+function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return { name: null, description: null };
+    return {
+        name: scalarFrontmatterValue(match[1], "name"),
+        description: scalarFrontmatterValue(match[1], "description"),
+    };
+}
+function scalarFrontmatterValue(frontmatter, key) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = frontmatter.match(new RegExp(`^${escapedKey}:\\s*(.+?)\\s*$`, "m"));
+    if (!match)
+        return null;
+    return match[1].replace(/^["']|["']$/g, "").trim();
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "llm-cli-gateway",
-      "version": "2.14.1",
+      "version": "2.15.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "Local-first MCP gateway for cross-model review across native coding-agent CLIs and API-token LLMs with sessions, durable jobs, and validation receipts.",
   "license": "MIT",