codex-skills-mcp 1.3.2 → 1.4.0

package/README.md

@@ -12,7 +12,10 @@
 
 | 特性 | 说明 |
 |------|------|
-| **6 个 MCP Tools** | search_skills, read_skill, load_skill_file, list_skill_files, list_categories, plan_workflow |
+| **8 个 MCP Tools** | search_skills, read_skill, load_skill_file, list_skill_files, list_categories, plan_workflow, skill_status, diagnostics |
+| **Agent 行为合约** | server instructions + 工具描述 + 返回体尾部三层强化同一套 5 步工作流（见 [docs/AGENT-PROTOCOL.md](docs/AGENT-PROTOCOL.md)） |
+| **缓存状态可见** | search/plan 结果带 `[cached]` 徽标；read_skill 返回 `local_path`；skill_status 深度校验完整性 |
+| **活动日志与诊断** | 全部工具调用/下载/错误落 JSONL 日志；diagnostics 一键审计 |
 | **三层渐进加载** | 检索(~500 tokens) → 阅读(~5K tokens) → 深入(按需) |
 | **中文搜索优化** | CJK bigram 分词 + Leading Words 权重 |
 | **零外部 AI 依赖** | 纯关键词搜索，不需要 embedding 模型 |
@@ -32,7 +35,7 @@ npx -y codex-skills-mcp@latest
 
 1. 从远端技能库拉取清单 `skills_manifest.json`（约 108KB，仅首次）；
 2. 建立本地搜索索引（毫秒级）；
-3. 技能文件按需下载，缓存在当前目录 `.codex-skills-cache/`。
+3. 技能文件按需下载，缓存在 `~/.codex-skills-cache/`（可用 `--cache-dir` / `CODEX_SKILLS_CACHE_DIR` 覆盖）。
 
 ### 2. 本地模式（可选）
 
@@ -144,10 +147,11 @@ ngrok http 3456
 ```mermaid
 flowchart LR
     A["启动 MCP"] --> B["拉取清单 manifest + 建本地索引"]
-    B --> C["search_skills 秒出结果"]
-    C --> D["read_skill 按需拉取技能全文"]
-    D --> E["load_skill_file 按需读脚本/配置"]
-    E --> F["Agent 在本机执行"]
+    B --> C["plan_workflow / search_skills<br/>DISCOVER（[cached] 徽标）"]
+    C --> D["read_skill x N<br/>MATERIALIZE：完整下载+缓存"]
+    D --> E["skill_status 校验（可选）"]
+    E --> F["按 SKILL.md 从 local_path 执行<br/>load_skill_file 按需补读"]
+    F --> G["diagnostics / 汇报"]
 ```
 
 | 阶段 | 行为 | 耗时 |
@@ -167,9 +171,26 @@ flowchart LR
 
 前一个节点失败时自动降级到下一个；全部失败才会报错。
 
+### Agent 标准工作流（行为合约）
+
+服务端通过 initialize instructions、工具描述、返回体尾部三层向 Agent 强化同一套协议（措辞单点维护于 `src/lib/protocol.ts`）：
+
+1. **DISCOVER** — `plan_workflow` / `search_skills` 检索；`[cached]` 徽标 = 已在本地，分数相近优先选；
+2. **SELECT** — 选出覆盖任务的最小技能组合；
+3. **MATERIALIZE（必做）** — 对每个选定技能调用 `read_skill`，完整下载到本地并返回 `local_path`；
+4. **EXECUTE** — 严格按 SKILL.md 执行，脚本从 `local_path` 运行，禁止凭通用知识自行替代；
+5. **VERIFY & REPORT** — `skill_status` 校验缓存完整性；`diagnostics` 排障并审计。
+
+### 日志与诊断
+
+- 活动日志：`~/.codex-skills-cache/logs/mcp-activity-YYYY-MM-DD.jsonl`（按天分文件，保留 14 天，best-effort 不影响主流程）；
+- 记录事件：`tool_call` / `tool_result` / `download_skill_start` / `download_skill_complete` / `tool_error` / `server_start`；
+- `diagnostics` 工具返回：近期调用、近期错误、缓存统计（已缓存技能数/体积）、清单新鲜度与配置摘要；
+- 本地模式（`--skills-dir`）不写文件日志，仅镜像到 stderr。
+
 ### 缓存与增量同步
 
-- 清单与技能文件缓存在当前目录 `.codex-skills-cache/`，二次启动秒级完成；
+- 清单与技能文件缓存在 `~/.codex-skills-cache/`，二次启动秒级完成；
 - 每个技能带 `.codex-skills.tree.json` 标记（文件列表 + 完成状态）；
 - 已完整下载的技能直接本地读取，不重复请求远端；
 - 中断的下载支持断点续传：按文件大小比对，只补拉缺失/不完整的文件；
@@ -180,7 +201,7 @@ flowchart LR
 
 ### 🔍 search_skills
 
-搜索技能库，Agent 的主入口。
+搜索技能库，Agent 的主入口（协议 STEP 1）。结果带 `[cached]` 徽标与"下一步必须 read_skill 物化"的协议尾部。
 
 ```
 input:  { query: "前端性能优化", category?: "01_代码工程与架构", limit?: 8 }
@@ -198,7 +219,7 @@ output: 14 个分类 + 各自的技能数量
 
 ### 📖 read_skill
 
-读取技能的完整指令（SKILL.md）+ 文件结构 + 环境依赖 + 子技能。
+物化技能（协议 STEP 3，执行前必调）：完整下载技能目录到本地缓存（已缓存则秒回），返回 SKILL.md 指令 + 文件结构 + 依赖 + **Cache & Execution 段（local_path / 完整性 / setup 命令）** + 子技能。
 
 ```
 input:  { name: "MediaCrawler" }
@@ -227,28 +248,48 @@ output: 目录树
 
 ### 🔗 plan_workflow
 
-给定任务描述，推荐可组合使用的技能。
+给定任务描述，产出可组合技能的**有序执行计划草稿**（带 `[cached]` 徽标），并强制"先 read_skill 全部选定技能再开工"。
 
 ```
 input:  { task_description: "把技术博客做成小红书图文" }
 output: 推荐技能列表 + 分类分组
 ```
 
-## 使用流程
+### ✅ skill_status
+
+深度校验一个或多个技能的本地缓存完整性（逐文件大小核对，只读不下载）。
+
+``
+input:  { names: "KrillinAI, videocut-skills" }
+output: cached/complete/local_path/files_total/files_missing/completed_at
+```
+
+### 🩺 diagnostics
+
+审计与排障：近期工具调用、近期错误（活动日志）、缓存统计、清单新鲜度、配置摘要。
+
+``
+input:  { include_log?: true, log_lines?: 20 }
+output: Server / Manifest / Local skill cache / Recent errors / Recent tool calls
+```
+
+## 使用流程（示例）
 
 ```
 用户: "帮我把这个视频翻译成中文字幕"
 
-Agent → search_skills("视频字幕翻译")
-     → 命中: KrillinAI, videocut-skills, VideoClaw
+Agent → plan_workflow("把视频翻译成中文字幕")          # DISCOVER：拿到组合计划
+Agent → search_skills("视频字幕翻译")                   # DISCOVER：精确定位
+     → 命中: KrillinAI, videocut-skills, VideoClaw      # [cached] 徽标优先
 
-Agent → read_skill("KrillinAI")
-     → 获取 SKILL.md 指令，了解怎么用
+Agent → read_skill("KrillinAI")                         # MATERIALIZE：完整下载
+     → 返回 SKILL.md + local_path + 依赖
+Agent → read_skill("videocut-skills")                   # 每个选定技能都要物化
 
-Agent → load_skill_file("KrillinAI", "README.md")
-     → 获取详细配置参数
+Agent → skill_status("KrillinAI, videocut-skills")      # VERIFY：确认缓存完整
 
-Agent → 按 SKILL.md 指令执行任务
+Agent → 按 SKILL.md 从 local_path 执行任务               # EXECUTE：严格遵循指令
+     → 需要补充文件时 load_skill_file(...)
 ```
 
 ## 配置参考
@@ -275,6 +316,8 @@ Agent → 按 SKILL.md 指令执行任务
 
 | 问题 | 处理 |
 |------|------|
+| Agent 读了 SKILL.md 却不按指令执行 | v1.4.0 起三层合约强制 5 步协议；仍异常时用 `diagnostics` 审计该 Agent 实际调用序列 |
+| 想看 Agent 到底做了什么 | `diagnostics` 或直接读 `~/.codex-skills-cache/logs/mcp-activity-*.jsonl` |
 | npx 首次运行较慢 | 首次需下载 npm 包 + 拉取清单，属正常；之后走缓存 |
 | 日志出现 `Network warning` | 当前加速节点失败，自动降级到下一个，可忽略 |
 | 想强制更新技能内容 | 删除 `.codex-skills-cache/` 后重启，或设 `--manifest-ttl 60` 让清单自动高频刷新 |

package/dist/config.d.ts

@@ -10,6 +10,8 @@ export interface Config {
     downloadConcurrency: number;
     /** Manifest cache TTL in milliseconds. Default 24 hours. 0 = never refresh. */
     manifestTTL: number;
+    /** Base download timeout for skill files in milliseconds. Default: 30000 (30s). */
+    downloadTimeout: number;
 }
 /**
  * Parse config from CLI args and env vars.

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;CACrB;AAuBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CA0GlD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,EAAE,CAGlE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;CACzB;AAuBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAsHlD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,EAAE,CAGlE"}

package/dist/config.js

@@ -102,6 +102,16 @@ export function parseConfig(args) {
         console.error("Error: --download-concurrency must be a positive integer");
         process.exit(1);
     }
+    // Base download timeout for skill files (default 30 seconds). Configurable via
+    // --download-timeout <seconds> or CODEX_SKILLS_DOWNLOAD_TIMEOUT env var.
+    const timeoutArg = getArg("--download-timeout");
+    const timeoutEnv = process.env.CODEX_SKILLS_DOWNLOAD_TIMEOUT;
+    const downloadTimeoutSeconds = parseInt(timeoutArg || timeoutEnv || "30", 10);
+    if (!Number.isInteger(downloadTimeoutSeconds) || downloadTimeoutSeconds < 1) {
+        console.error("Error: --download-timeout must be a positive integer");
+        process.exit(1);
+    }
+    const downloadTimeout = downloadTimeoutSeconds * 1000;
     return {
         skillsDir,
         manifestPath,
@@ -112,7 +122,8 @@ export function parseConfig(args) {
         githubToken,
         useCnMirror,
         downloadConcurrency,
-        manifestTTL
+        manifestTTL,
+        downloadTimeout
     };
 }
 export function loadManifest(manifestPath) {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -23,37 +23,45 @@ import { createRequire } from "node:module";
 import { parseConfig, loadManifest } from "./config.js";
 import { SkillSearchEngine } from "./search/index.js";
 import { SkillLoader } from "./loader/index.js";
+import { SERVER_INSTRUCTIONS } from "./lib/protocol.js";
+import { initLogger, logEvent } from "./lib/logger.js";
 import { registerSearchSkills } from "./tools/search-skills.js";
 import { registerListCategories } from "./tools/list-categories.js";
 import { registerReadSkill } from "./tools/read-skill.js";
 import { registerLoadSkillFile } from "./tools/load-skill-file.js";
 import { registerListSkillFiles } from "./tools/list-skill-files.js";
 import { registerPlanWorkflow } from "./tools/plan-workflow.js";
+import { registerSkillStatus } from "./tools/skill-status.js";
+import { registerDiagnostics } from "./tools/diagnostics.js";
 // Single source of truth for the version: read package.json instead of
 // hardcoding it here, so releasing a new version only requires one bump.
 const require = createRequire(import.meta.url);
 const PKG_VERSION = require("../package.json").version;
-function createServer(searchEngine, loader) {
-    const server = new McpServer({
-        name: "codex-skills",
-        version: PKG_VERSION,
+function createServer(config, searchEngine, loader) {
+    const server = new McpServer({ name: "codex-skills", version: PKG_VERSION }, {
+        // The agent-facing behavioral contract (docs/AGENT-PROTOCOL.md) is
+        // returned to clients in the initialize result and reinforced in every
+        // tool description and result footer.
+        instructions: SERVER_INSTRUCTIONS,
     });
-    registerSearchSkills(server, searchEngine);
+    registerSearchSkills(server, searchEngine, loader);
     registerListCategories(server, searchEngine);
     registerReadSkill(server, searchEngine, loader);
     registerLoadSkillFile(server, searchEngine, loader);
     registerListSkillFiles(server, searchEngine, loader);
-    registerPlanWorkflow(server, searchEngine);
+    registerPlanWorkflow(server, searchEngine, loader);
+    registerSkillStatus(server, searchEngine, loader);
+    registerDiagnostics(server, config, searchEngine, loader, PKG_VERSION);
     return server;
 }
-async function startStdio(searchEngine, loader) {
-    const server = createServer(searchEngine, loader);
-    console.error("[codex-skills-mcp] 6 tools registered, starting stdio server...");
+async function startStdio(config, searchEngine, loader) {
+    const server = createServer(config, searchEngine, loader);
+    console.error("[codex-skills-mcp] 8 tools registered, starting stdio server...");
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[codex-skills-mcp] Server running on stdio");
 }
-async function startHTTP(searchEngine, loader, port) {
+async function startHTTP(config, searchEngine, loader, port) {
     // Dynamic import to avoid loading express in stdio mode
     const { default: express } = await import("express");
     const app = express();
@@ -104,7 +112,7 @@ async function startHTTP(searchEngine, loader, port) {
                     sessions.delete(sid);
             };
             // Each session gets its own server instance
-            const server = createServer(searchEngine, loader);
+            const server = createServer(config, searchEngine, loader);
             await server.connect(transport);
         }
         await transport.handleRequest(req, res, req.body);
@@ -142,7 +150,7 @@ async function startHTTP(searchEngine, loader, port) {
             activeSessions: sessions.size,
         });
     });
-    console.error("[codex-skills-mcp] 6 tools registered, starting HTTP server...");
+    console.error("[codex-skills-mcp] 8 tools registered, starting HTTP server...");
     app.listen(port, () => {
         console.error(`[codex-skills-mcp] HTTP server running at http://localhost:${port}/mcp`);
         console.error(`[codex-skills-mcp] Health check: http://localhost:${port}/health`);
@@ -154,6 +162,10 @@ async function main() {
     // Parse configuration
     const config = parseConfig(args);
     if (config.isRemote) {
+        // Activity log lives under <cacheDir>/logs (remote mode only, so local
+        // skill libraries are never polluted). See docs/IMPROVEMENT-PLAN.md §7.
+        initLogger(config.skillsDir);
+        logEvent("info", "server_start", { detail: `v${PKG_VERSION} remote mode` });
         const { initRemote, fetchManifest } = await import("./remote/github.js");
         console.error("[codex-skills-mcp] Initializing remote GitHub fetching...");
         await initRemote(config);
@@ -176,10 +188,10 @@ async function main() {
         // Parse port
         const portIdx = args.indexOf("--port");
         const port = portIdx !== -1 && args[portIdx + 1] ? parseInt(args[portIdx + 1], 10) : 3456;
-        await startHTTP(searchEngine, loader, port);
+        await startHTTP(config, searchEngine, loader, port);
     }
     else {
-        await startStdio(searchEngine, loader);
+        await startStdio(config, searchEngine, loader);
     }
 }
 main().catch((err) => {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,uEAAuE;AACvE,yEAAyE;AACzE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,OAAiB,CAAC;AAEjE,SAAS,YAAY,CACnB,YAA+B,EAC/B,MAAmB;IAEnB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,WAAW;KACrB,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC3C,sBAAsB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC7C,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAChD,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IACpD,sBAAsB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IACrD,oBAAoB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE3C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,YAA+B,EAC/B,MAAmB;IAEnB,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAElD,OAAO,CAAC,KAAK,CAAC,iEAAiE,CAAC,CAAC;IAEjF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;AAC9D,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,YAA+B,EAC/B,MAAmB,EACnB,IAAY;IAEZ,wDAAwD;IACxD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IAErD,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAExB,gEAAgE;IAChE,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,0BAA0B;IAKjE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEjD,uCAAuC;IACvC,SAAS,YAAY,CAAC,GAAW;QAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,KAAK;YAAE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7C,CAAC;IAED,sDAAsD;IACtD,WAAW,CAAC,GAAG,EAAE;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YACpC,IAAI,GAAG,GAAG,KAAK,CAAC,YAAY,GAAG,cAAc,EAAE,CAAC;gBAC9C,OAAO,CAAC,KAAK,CAAC,6CAA6C,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;gBACrF,IAAI,CAAC;oBAAC,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;gBACzD,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;IACH,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,2CAA2C;IAEtE,yFAAyF;IACzF,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAClC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAuB,CAAC;QAEtE,IAAI,SAAwC,CAAC;QAE7C,IAAI,SAAS,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,SAAS,CAAC;YAC/C,YAAY,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,cAAc;YACd,SAAS,GAAG,IAAI,6BAA6B,CAAC;gBAC5C,kBAAkB,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC7C,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE;oBAC5B,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;oBAC3D,OAAO,CAAC,KAAK,CAAC,mCAAmC,GAAG,EAAE,CAAC,CAAC;gBAC1D,CAAC;aACF,CAAC,CAAC;YAEH,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE;gBACvB,MAAM,GAAG,GAAI,SAAiB,CAAC,SAAS,CAAC;gBACzC,IAAI,GAAG;oBAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChC,CAAC,CAAC;YAEF,4CAA4C;YAC5C,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;YAClD,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;QAED,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,uDAAuD;IACvD,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACjC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAuB,CAAC;QACtE,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,+BAA+B,EAAE,CAAC,CAAC;YACjE,OAAO;QACT,CAAC;QACD,YAAY,CAAC,SAAS,CAAC,CAAC;QACxB,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,SAAS,CAAC;QACrD,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,sCAAsC;IACtC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACpC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAuB,CAAC;QACtE,IAAI,SAAS,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,SAAS,CAAC;YACrD,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACxC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACxB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,eAAe;IACf,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QAC/B,GAAG,CAAC,IAAI,CAAC;YACP,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,WAAW;YACpB,MAAM,EAAE,YAAY,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YAC3E,cAAc,EAAE,QAAQ,CAAC,IAAI;SAC9B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,KAAK,CAAC,gEAAgE,CAAC,CAAC;IAEhF,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;QACpB,OAAO,CAAC,KAAK,CAAC,8DAA8D,IAAI,MAAM,CAAC,CAAC;QACxF,OAAO,CAAC,KAAK,CAAC,qDAAqD,IAAI,SAAS,CAAC,CAAC;QAClF,OAAO,CAAC,KAAK,CACX,qFAAqF,CACtF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,sBAAsB;IACtB,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAEjC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACzE,OAAO,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC3E,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;QACzB,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,gBAAgB;IAChB,OAAO,CAAC,KAAK,CAAC,6CAA6C,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACnD,OAAO,CAAC,KAAK,CAAC,6BAA6B,QAAQ,CAAC,MAAM,SAAS,CAAC,CAAC;IAErE,qBAAqB;IACrB,MAAM,YAAY,GAAG,IAAI,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,YAAY,CAAC,aAAa,EAAE,CAAC;IAChD,OAAO,CAAC,KAAK,CACX,mCAAmC,UAAU,CAAC,MAAM,eAAe;QACjE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,iBAAiB,CACxE,CAAC;IAEF,sBAAsB;IACtB,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAEjD,2BAA2B;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAExC,IAAI,OAAO,EAAE,CAAC;QACZ,aAAa;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAE1F,MAAM,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,MAAM,UAAU,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/logger.d.ts

@@ -0,0 +1,36 @@
+export type LogLevel = "info" | "warn" | "error";
+export interface LogEvent {
+    ts: string;
+    level: LogLevel;
+    event: string;
+    tool?: string;
+    skill?: string;
+    duration_ms?: number;
+    ok?: boolean;
+    detail?: string;
+    error?: string;
+}
+/** Enable file logging under <cacheDir>/logs. Safe to call once at startup. */
+export declare function initLogger(cacheDir: string): void;
+/** True when file logging is active (used by diagnostics output). */
+export declare function loggerActive(): boolean;
+/** Log dir path (for diagnostics output). */
+export declare function logDirPath(): string | null;
+/** Append one event. Mirrors to stderr; never throws. */
+export declare function logEvent(level: LogLevel, event: string, fields?: Omit<LogEvent, "ts" | "level" | "event">): void;
+/**
+ * Read recent events across log files (newest first), optionally filtered by
+ * level and/or event type. Returns at most `limit` entries. Never throws.
+ */
+export declare function readRecentEvents(options?: {
+    limit?: number;
+    level?: LogLevel;
+    event?: string;
+}): LogEvent[];
+/**
+ * Wrap a tool handler with call/result/error logging. Handlers that return
+ * error-text instead of throwing should additionally call logEvent themselves
+ * in their catch block (see tools/*).
+ */
+export declare function withToolLogging<R>(tool: string, argSummary: Record<string, unknown>, fn: () => Promise<R>): Promise<R>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOjD;AAED,qEAAqE;AACrE,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED,6CAA6C;AAC7C,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAE1C;AAgBD,yDAAyD;AACzD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,OAAO,GAAG,OAAO,CAAM,GACpD,IAAI,CA2BN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,QAAQ,EAAE,CAiC/G;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAgBZ"}

package/dist/lib/logger.js

@@ -0,0 +1,143 @@
+/**
+ * Best-effort JSONL activity logger.
+ *
+ * - File per day: <cacheDir>/logs/mcp-activity-YYYY-MM-DD.jsonl
+ * - Retention: last 14 files swept at most once per day per process.
+ * - NEVER throws: every fs operation is wrapped; logging must not break tools.
+ * - Key events are mirrored to stderr for local debugging (MCP-safe: stderr,
+ *   never stdout).
+ */
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+const LOG_FILE_PREFIX = "mcp-activity-";
+const RETENTION_FILES = 14;
+/** Active log directory; null = file logging disabled (e.g. local mode). */
+let logDir = null;
+let lastSweep = 0;
+/** Enable file logging under <cacheDir>/logs. Safe to call once at startup. */
+export function initLogger(cacheDir) {
+    try {
+        logDir = join(cacheDir, "logs");
+        mkdirSync(logDir, { recursive: true });
+    }
+    catch {
+        logDir = null;
+    }
+}
+/** True when file logging is active (used by diagnostics output). */
+export function loggerActive() {
+    return logDir !== null;
+}
+/** Log dir path (for diagnostics output). */
+export function logDirPath() {
+    return logDir;
+}
+function sweep() {
+    if (!logDir)
+        return;
+    try {
+        const files = readdirSync(logDir)
+            .filter((f) => f.startsWith(LOG_FILE_PREFIX) && f.endsWith(".jsonl"))
+            .sort();
+        while (files.length > RETENTION_FILES) {
+            unlinkSync(join(logDir, files.shift()));
+        }
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Append one event. Mirrors to stderr; never throws. */
+export function logEvent(level, event, fields = {}) {
+    const entry = { ts: new Date().toISOString(), level, event, ...fields };
+    const mirror = [
+        `[codex-skills-mcp] ${level} ${event}`,
+        fields.tool ? ` tool=${fields.tool}` : "",
+        fields.skill ? ` skill=${fields.skill}` : "",
+        fields.error ? ` error=${fields.error}` : "",
+    ].join("");
+    console.error(mirror);
+    if (!logDir)
+        return;
+    try {
+        const day = entry.ts.slice(0, 10);
+        appendFileSync(join(logDir, `${LOG_FILE_PREFIX}${day}.jsonl`), JSON.stringify(entry) + "\n", "utf-8");
+        const now = Date.now();
+        if (now - lastSweep > 24 * 3600 * 1000) {
+            lastSweep = now;
+            sweep();
+        }
+    }
+    catch {
+        // best-effort: ignore disk errors entirely
+    }
+}
+/**
+ * Read recent events across log files (newest first), optionally filtered by
+ * level and/or event type. Returns at most `limit` entries. Never throws.
+ */
+export function readRecentEvents(options = {}) {
+    const { limit = 20, level, event } = options;
+    if (!logDir || limit <= 0)
+        return [];
+    const out = [];
+    try {
+        const files = readdirSync(logDir)
+            .filter((f) => f.startsWith(LOG_FILE_PREFIX) && f.endsWith(".jsonl"))
+            .sort()
+            .reverse();
+        outer: for (const file of files) {
+            let lines;
+            try {
+                lines = readFileSync(join(logDir, file), "utf-8").split("\n").filter(Boolean);
+            }
+            catch {
+                continue;
+            }
+            for (let i = lines.length - 1; i >= 0; i--) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(lines[i]);
+                }
+                catch {
+                    continue;
+                }
+                if (level && parsed.level !== level)
+                    continue;
+                if (event && parsed.event !== event)
+                    continue;
+                out.push(parsed);
+                if (out.length >= limit)
+                    break outer;
+            }
+        }
+    }
+    catch {
+        // best-effort
+    }
+    return out;
+}
+/**
+ * Wrap a tool handler with call/result/error logging. Handlers that return
+ * error-text instead of throwing should additionally call logEvent themselves
+ * in their catch block (see tools/*).
+ */
+export async function withToolLogging(tool, argSummary, fn) {
+    const startedAt = Date.now();
+    logEvent("info", "tool_call", { tool, detail: JSON.stringify(argSummary) });
+    try {
+        const result = await fn();
+        logEvent("info", "tool_result", { tool, ok: true, duration_ms: Date.now() - startedAt });
+        return result;
+    }
+    catch (err) {
+        logEvent("error", "tool_result", {
+            tool,
+            ok: false,
+            duration_ms: Date.now() - startedAt,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/lib/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"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"}

package/dist/lib/protocol.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent protocol texts — the single source of truth for the behavioral
+ * contract enforced across three surfaces: server `instructions`, tool
+ * descriptions, and tool-result footers. Keep the wording consistent here so
+ * every surface reinforces the same 5-step protocol (docs/AGENT-PROTOCOL.md).
+ */
+/** Server-level instructions returned in the MCP initialize result. */
+export declare const SERVER_INSTRUCTIONS = "Codex-Skills: 190+ expert skills fetched on demand \u2014 no pre-install needed. Daily use progressively caches skills locally.\n\nMANDATORY 5-step protocol for any task a skill could help with:\n1. DISCOVER \u2014 plan_workflow(task) and/or search_skills(query). \"[cached]\" means the skill is already on local disk; prefer cached skills when scores are close.\n2. SELECT \u2014 choose the smallest set of skills that together cover the task.\n3. MATERIALIZE \u2014 call read_skill(name) for EVERY selected skill BEFORE starting work. Each call downloads the COMPLETE skill (SKILL.md, scripts, configs, references) into the local cache and returns the instructions plus local_path. Never skip or partial-skip this step.\n4. EXECUTE \u2014 follow each loaded SKILL.md verbatim and run its scripts from local_path (run its Setup command first if one is listed). NEVER improvise a substitute for a loaded skill. load_skill_file is only for reading extra files.\n5. VERIFY & REPORT \u2014 skill_status(names) confirms cache completeness; report which skills you used. On failures, use diagnostics.\n\nForbidden anti-patterns: reading SKILL.md and then doing the task from general knowledge; starting before every selected skill is materialized; rewriting a loaded skill's logic yourself.";
+/** search_skills result footer. */
+export declare const FOOTER_SEARCH = "\u25B6 PROTOCOL STEP 3 (required): call read_skill(name) for EVERY skill you select \u2014 each call downloads the complete skill to local disk (cached skills return instantly). Do NOT start the task until all selected skills are loaded; then execute strictly per each SKILL.md.";
+/** plan_workflow result footer. */
+export declare const FOOTER_PLAN = "\u25B6 PROTOCOL STEP 3 (required): call read_skill for EVERY skill in your final plan before starting \u2014 each call downloads the complete skill to local disk (cached skills return instantly). Then execute in the planned order, strictly following each SKILL.md, and report which skills you used.";
+/** read_skill result footer (after the Cache & Execution section). */
+export declare const FOOTER_READ = "\u25B6 PROTOCOL STEP 4: Execute the task by following the Instructions above exactly \u2014 run scripts from local_path. Do NOT improvise a substitute for this skill. Use load_skill_file only when you need additional files.";
+/** skill_status result footer. */
+export declare const FOOTER_STATUS = "\u25B6 If all selected skills are complete, proceed to EXECUTE from each local_path. Incomplete skills: re-call read_skill to resume the download.";
+/** diagnostics result footer. */
+export declare const FOOTER_DIAGNOSTICS = "\u25B6 Fix the reported errors (network failures are often transient \u2014 retry read_skill), then resume the protocol at the failed step.";
+/** Cached badge used in search/plan results. */
+export declare const CACHED_BADGE = "[cached]";
+//# sourceMappingURL=protocol.d.ts.map

package/dist/lib/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/lib/protocol.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,0wCAS2J,CAAC;AAE5L,mCAAmC;AACnC,eAAO,MAAM,aAAa,2RAAiR,CAAC;AAE5S,mCAAmC;AACnC,eAAO,MAAM,WAAW,+SAAqS,CAAC;AAE9T,sEAAsE;AACtE,eAAO,MAAM,WAAW,oOAA0N,CAAC;AAEnP,kCAAkC;AAClC,eAAO,MAAM,aAAa,uJAAkJ,CAAC;AAE7K,iCAAiC;AACjC,eAAO,MAAM,kBAAkB,gJAAsI,CAAC;AAEtK,gDAAgD;AAChD,eAAO,MAAM,YAAY,aAAa,CAAC"}

package/dist/lib/protocol.js

@@ -0,0 +1,30 @@
+/**
+ * Agent protocol texts — the single source of truth for the behavioral
+ * contract enforced across three surfaces: server `instructions`, tool
+ * descriptions, and tool-result footers. Keep the wording consistent here so
+ * every surface reinforces the same 5-step protocol (docs/AGENT-PROTOCOL.md).
+ */
+/** Server-level instructions returned in the MCP initialize result. */
+export const SERVER_INSTRUCTIONS = `Codex-Skills: 190+ expert skills fetched on demand — no pre-install needed. Daily use progressively caches skills locally.
+
+MANDATORY 5-step protocol for any task a skill could help with:
+1. DISCOVER — plan_workflow(task) and/or search_skills(query). "[cached]" means the skill is already on local disk; prefer cached skills when scores are close.
+2. SELECT — choose the smallest set of skills that together cover the task.
+3. MATERIALIZE — call read_skill(name) for EVERY selected skill BEFORE starting work. Each call downloads the COMPLETE skill (SKILL.md, scripts, configs, references) into the local cache and returns the instructions plus local_path. Never skip or partial-skip this step.
+4. EXECUTE — follow each loaded SKILL.md verbatim and run its scripts from local_path (run its Setup command first if one is listed). NEVER improvise a substitute for a loaded skill. load_skill_file is only for reading extra files.
+5. VERIFY & REPORT — skill_status(names) confirms cache completeness; report which skills you used. On failures, use diagnostics.
+
+Forbidden anti-patterns: reading SKILL.md and then doing the task from general knowledge; starting before every selected skill is materialized; rewriting a loaded skill's logic yourself.`;
+/** search_skills result footer. */
+export const FOOTER_SEARCH = `▶ PROTOCOL STEP 3 (required): call read_skill(name) for EVERY skill you select — each call downloads the complete skill to local disk (cached skills return instantly). Do NOT start the task until all selected skills are loaded; then execute strictly per each SKILL.md.`;
+/** plan_workflow result footer. */
+export const FOOTER_PLAN = `▶ PROTOCOL STEP 3 (required): call read_skill for EVERY skill in your final plan before starting — each call downloads the complete skill to local disk (cached skills return instantly). Then execute in the planned order, strictly following each SKILL.md, and report which skills you used.`;
+/** read_skill result footer (after the Cache & Execution section). */
+export const FOOTER_READ = `▶ PROTOCOL STEP 4: Execute the task by following the Instructions above exactly — run scripts from local_path. Do NOT improvise a substitute for this skill. Use load_skill_file only when you need additional files.`;
+/** skill_status result footer. */
+export const FOOTER_STATUS = `▶ If all selected skills are complete, proceed to EXECUTE from each local_path. Incomplete skills: re-call read_skill to resume the download.`;
+/** diagnostics result footer. */
+export const FOOTER_DIAGNOSTICS = `▶ Fix the reported errors (network failures are often transient — retry read_skill), then resume the protocol at the failed step.`;
+/** Cached badge used in search/plan results. */
+export const CACHED_BADGE = "[cached]";
+//# sourceMappingURL=protocol.js.map

package/dist/lib/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/lib/protocol.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;2LASwJ,CAAC;AAE5L,mCAAmC;AACnC,MAAM,CAAC,MAAM,aAAa,GAAG,8QAA8Q,CAAC;AAE5S,mCAAmC;AACnC,MAAM,CAAC,MAAM,WAAW,GAAG,kSAAkS,CAAC;AAE9T,sEAAsE;AACtE,MAAM,CAAC,MAAM,WAAW,GAAG,uNAAuN,CAAC;AAEnP,kCAAkC;AAClC,MAAM,CAAC,MAAM,aAAa,GAAG,+IAA+I,CAAC;AAE7K,iCAAiC;AACjC,MAAM,CAAC,MAAM,kBAAkB,GAAG,mIAAmI,CAAC;AAEtK,gDAAgD;AAChD,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC"}

package/dist/loader/index.d.ts

@@ -1,5 +1,6 @@
 import type { ManifestEntry, Config } from "../config.js";
 import type { ProgressCallback } from "../remote/github.js";
+import { type SkillCacheState } from "../remote/github.js";
 export interface SkillStructure {
     files: FileNode[];
     sub_skills: SubSkillInfo[];
@@ -68,5 +69,15 @@ export declare class SkillLoader {
      * List files in a subdirectory of a skill.
      */
     listSkillFiles(entry: ManifestEntry, subPath?: string, maxDepth?: number): Promise<FileNode[]>;
+    /**
+     * Deep cache-state check for one skill. Read-only: never triggers a
+     * download. In local mode every skill is on disk by definition.
+     */
+    cacheState(entry: ManifestEntry): SkillCacheState;
+    /**
+     * Light cache check (marker + completedAt only) for [cached] badges in
+     * search results. In local mode always true.
+     */
+    isCached(entry: ManifestEntry): boolean;
 }
 //# sourceMappingURL=index.d.ts.map