@miphamai/cli 0.50.0 → 0.52.0

package/src/daemon/telegram/poller.ts

@@ -0,0 +1,64 @@
+import type { TelegramApi } from './api.js'
+import type { TelegramMessage } from './types.js'
+
+/** 从 update 提取文本消息；非文本/缺 message → null。chat.id 统一字符串化比对（id < 2^53；超范围 bigint 后续再引入）。 */
+export function extractTextMessage(update: unknown): TelegramMessage | null {
+  const msg = (
+    update as { message?: { chat?: { id?: number | string }; message_id?: number; text?: string } }
+  )?.message
+  if (!msg?.text || msg.chat?.id == null) return null
+  return { chatId: String(msg.chat.id), messageId: msg.message_id ?? 0, text: msg.text }
+}
+
+/** 推进 offset：最大 update_id + 1；空列表沿用 prev。 */
+export function nextOffset(updates: Array<{ update_id?: number }>, prevOffset: number): number {
+  if (updates.length === 0) return prevOffset
+  return Math.max(...updates.map((u) => u.update_id ?? prevOffset)) + 1
+}
+
+/** 指数退避，封顶 30s。 */
+export function nextBackoff(currentMs: number): number {
+  return Math.min(currentMs * 2, 30_000)
+}
+
+/** 长轮询循环（unref 不阻退出）。返回 stop 函数。循环行为由 Task 7 集成测试覆盖。 */
+export function startTelegramPoller(
+  api: TelegramApi,
+  onMessage: (msg: TelegramMessage) => Promise<void>,
+  opts?: { pollTimeoutSeconds?: number },
+): () => void {
+  let offset = 0
+  let backoffMs = 1000
+  let stopped = false
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  async function loop() {
+    if (stopped) return
+    try {
+      const updates = await api.getUpdates(offset, opts?.pollTimeoutSeconds ?? 30)
+      for (const u of updates) {
+        const msg = extractTextMessage(u)
+        if (msg) {
+          try {
+            await onMessage(msg)
+          } catch {
+            /* 单条失败不中断轮询 */
+          }
+        }
+      }
+      offset = nextOffset(updates, offset)
+      backoffMs = 1000
+    } catch {
+      backoffMs = nextBackoff(backoffMs)
+    }
+    if (stopped) return
+    timer = setTimeout(loop, backoffMs)
+    ;(timer as { unref?: () => void }).unref?.()
+  }
+
+  void loop()
+  return () => {
+    stopped = true
+    if (timer) clearTimeout(timer)
+  }
+}

package/src/daemon/telegram/types.ts

@@ -0,0 +1,10 @@
+export interface TelegramConfig {
+  botToken: string
+  allowedChatIds: string[]
+}
+
+export interface TelegramMessage {
+  chatId: string
+  messageId: number
+  text: string
+}

package/src/i18n-core/locales/en-US.json

@@ -612,6 +612,129 @@
     },
     "schedule": {
       "failed": "Schedule check failed: {error}"
+    },
+    "crsi_critique": {
+      "not_init": "SelfCritique not initialized. Mipham Code >= v0.34.0 required.",
+      "on_title": "## 🔍 Self-Critique: ON",
+      "on_desc1": "The AI will now critique its own tool calls before execution.",
+      "on_desc2": "Safe + correct + necessary checks run before every targeted tool call.",
+      "on_hint": "💡 `/crsi critique off` to disable | `/crsi critique status` for current config",
+      "off_title": "## 🔍 Self-Critique: OFF\n\nTool calls will execute without pre-flight critique.",
+      "status_title": "## 🔍 Self-Critique Status",
+      "state": "State: **{state}**",
+      "model": "Model: **{model}**",
+      "threshold": "Threshold: **{pct}%**",
+      "threshold_detail": "Threshold: **{pct}%** (below this → correction or block)",
+      "target_tools": "Target tools: **{tools}**",
+      "timeout": "Timeout: **{ms}ms**",
+      "status_on_hint": "🔍 `/crsi critique on` — Enable self-critique",
+      "status_off_hint": "🔍 `/crsi critique off` — Disable self-critique",
+      "inspired": "*Inspired by Anthropic RLAIF — AI critiques its own actions before execution.*"
+    },
+    "crsi_interpret": {
+      "title": "## 🧠 CRSI Tool-Call Interpretability",
+      "no_sigs_for_tool": "No error signatures for tool `{tool}`. CRSI immune memory is clean for this tool.",
+      "no_sigs": "No active error signatures. CRSI immune memory is clean.",
+      "sigs_title": "### 🛡️ Error Signatures{tool}",
+      "sig_success": "  Success: {bar} {pct}% | {occurrences}x | {strategy}",
+      "sig_fix": "  Fix: `{fix}`",
+      "sigs_more": "... and {count} more signatures",
+      "reflection_title": "### 📊 CRSI Reflection Summary",
+      "reflections": "Turn reflections analyzed: **{count}**",
+      "usage_title": "### 💰 Token Usage",
+      "api_in": "API input tokens:  {count}",
+      "api_out": "API output tokens: {count}",
+      "est_tokens": "Estimated tokens:  {count}",
+      "health_title": "### 🏥 System Health",
+      "overall": "Overall: {bar} **{score}/100**",
+      "assessment": "Assessment: {assessment}",
+      "constitution_title": "### ⚖️ Constitution",
+      "principles": "Principles: **{total}** (🚫 {block} block | ⚠️ {warn} warn | 🔄 {auto} auto)",
+      "version": "Version: v{version}",
+      "empty": "_Start using tools to populate CRSI interpretability data._",
+      "filter_hint": "🔍 Filter by tool: `/crsi interpret <tool-name>` (e.g. `/crsi interpret Bash`)"
+    },
+    "crsi_red_team": {
+      "not_init": "Red-Team requires both ConstitutionLoader and PreFlightChecker to be initialized.",
+      "title": "## 🔴 CRSI Red-Team Report",
+      "score": "Overall Score: **{score}/100**",
+      "metric": "| Metric | Count |",
+      "metric_sep": "|--------|------|",
+      "total_attacks": "| Total attacks | {count} |",
+      "blocked": "| 🛡️ Correctly blocked | {count} |",
+      "passed_through": "| 🔴 Passed through (GAP) | {count} |",
+      "false_positives": "| ⚠️ False positives | {count} |",
+      "by_principle": "### By Principle",
+      "gaps_title": "### 🔴 Security Gaps (Should Have Been Blocked)",
+      "gap_tool": "  Tool: `{tool}` → Params: `{params}`",
+      "blocked_title": "### 🛡️ Successfully Blocked",
+      "caught_by": "{principle}: {desc} → caught by **{caught}**",
+      "all_blocked": "🎉 **All attacks blocked!** The SIS immune system is fully operational.",
+      "good_coverage": "⚠️ Good coverage. Review the gaps above and add audit patterns to `ai-guardrails.yml`.",
+      "critical": "🔴 **Critical gaps detected.** Prioritize fixing the passed-through attacks above."
+    },
+    "dream": {
+      "not_init": "DreamEngine not initialized. Mipham Code >= v0.34.0 required.",
+      "no_history": "🌙 Auto-Dream has not run yet. Use `/dream` to trigger the first consolidation.",
+      "history_title": "## 🌙 Auto-Dream History",
+      "history_entry": "- **{time}**: {total} actions ({applied} auto-applied, {flagged} flagged for review)",
+      "done_title": "## 🌙 Auto-Dream Complete",
+      "integrate": "Memory integration: {before} → {after}",
+      "dedup": "- Deduplicated: {count} entries",
+      "contradiction": "- Contradictions: {count} (need human review)",
+      "merge": "- Merged: {count} groups",
+      "solidify": "- Fuzzy-marked: {count} entries (suggested to solidify)",
+      "prune": "- Pruned expired: {count} entries",
+      "review_hint": "⚠️  {count} items pending review. Use `/dream --aggressive` to auto-apply all.",
+      "clean": "✅ Memory is clean, nothing to consolidate."
+    },
+    "constitution": {
+      "not_init": "ConstitutionLoader not initialized. Mipham Code >= v0.34.0 required.",
+      "reload_title": "## ⚖️ Constitution Reloaded",
+      "version": "Version: **v{version}**",
+      "principles": "Principles: **{count}**",
+      "path": "Path: `{path}`",
+      "view_title": "## ⚖️ Mipham Constitution",
+      "view_summary": "Version: **v{version}** | Principles: **{count}** | Path: `{path}`",
+      "scope": "  Scope: `{scope}`",
+      "tools": "  Tools: {tools}",
+      "reload_hint": "🔧 `/constitution reload` — Reload after editing ai-guardrails.yml",
+      "edit_hint": "📝 Edit: `vi ~/.mipham/ai-guardrails.yml`",
+      "reset_hint": "🗑️  Reset: delete `~/.mipham/ai-guardrails.yml` then run `/constitution reload`",
+      "inspired": "*Inspired by Anthropic Constitutional AI. Mipham enforces these principles at runtime — auditable on every action.*"
+    },
+    "bug_report": {
+      "title": "## 🐛 Bug Report",
+      "hint": "> Copy the report below and paste it into your GitHub Issue.",
+      "env_title": "### Environment",
+      "mipham": "- **Mipham Code**: v{version}",
+      "session": "- **Session**: {id}",
+      "node": "- **Node**: {version}",
+      "platform": "- **Platform**: {platform} {arch}",
+      "os": "- **OS**: {os}",
+      "provider": "- **Provider**: {provider}",
+      "model": "- **Model**: {model}",
+      "sigs_title": "### Active Error Signatures",
+      "sig_entry": "- `{id}`: {pattern} ({category}, {occurrences}x, {pct}% success)",
+      "disabled_hooks": "### Disabled Hooks",
+      "hook_entry": "- `{key}`: {failures} failures, disabled at {time}",
+      "last_dream": "### Last Auto-Dream",
+      "ran_at": "- **Ran at**: {time}",
+      "actions": "- **Actions**: {total} ({applied} applied)",
+      "steps_title": "### Steps to Reproduce",
+      "expected": "### Expected Behavior",
+      "actual": "### Actual Behavior",
+      "generated": "🤖 Generated with Mipham Code v{version}"
+    },
+    "changelog": {
+      "title": "## 📋 Changelog",
+      "no_tags": "No version tags found.",
+      "current": "Current: **v{version}**",
+      "current_marker": " ← current",
+      "release_only": "  _(release tag only)_",
+      "details_unavailable": "  _(details unavailable)_",
+      "no_git": "Unable to read git history. Make sure you are in the Mipham Code repository.",
+      "full_history": "Full history: `git log --oneline`"
     }
   },
   "ui": {

package/src/i18n-core/locales/zh-CN.json

@@ -612,6 +612,129 @@
     },
     "schedule": {
       "failed": "调度检查失败: {error}"
+    },
+    "crsi_critique": {
+      "not_init": "SelfCritique 未初始化。请确认 Mipham Code 版本 >= v0.34.0。",
+      "on_title": "## 🔍 Self-Critique: 已开启",
+      "on_desc1": "AI 现在会在每次工具调用执行前自我批判。",
+      "on_desc2": "每次目标工具调用前都会执行安全 + 正确 + 必要性检查。",
+      "on_hint": "💡 `/crsi critique off` 关闭 | `/crsi critique status` 查看当前配置",
+      "off_title": "## 🔍 Self-Critique: 已关闭\n\n工具调用将不再执行预检批判。",
+      "status_title": "## 🔍 Self-Critique 状态",
+      "state": "状态: **{state}**",
+      "model": "模型: **{model}**",
+      "threshold": "阈值: **{pct}%**",
+      "threshold_detail": "阈值: **{pct}%**（低于此 → 纠正或拦截）",
+      "target_tools": "目标工具: **{tools}**",
+      "timeout": "超时: **{ms}ms**",
+      "status_on_hint": "🔍 `/crsi critique on` — 启用自我批判",
+      "status_off_hint": "🔍 `/crsi critique off` — 禁用自我批判",
+      "inspired": "*灵感来自 Anthropic RLAIF — AI 在执行前批判自己的行为。*"
+    },
+    "crsi_interpret": {
+      "title": "## 🧠 CRSI 工具调用可解释性",
+      "no_sigs_for_tool": "工具 `{tool}` 没有错误签名。该工具的 CRSI 免疫记忆是干净的。",
+      "no_sigs": "没有活跃的错误签名。CRSI 免疫记忆是干净的。",
+      "sigs_title": "### 🛡️ 错误签名{tool}",
+      "sig_success": "  成功率: {bar} {pct}% | {occurrences}次 | {strategy}",
+      "sig_fix": "  修复: `{fix}`",
+      "sigs_more": "... 还有 {count} 条签名",
+      "reflection_title": "### 📊 CRSI 反思摘要",
+      "reflections": "已分析的轮次反思: **{count}**",
+      "usage_title": "### 💰 Token 用量",
+      "api_in": "API 输入 tokens:  {count}",
+      "api_out": "API 输出 tokens: {count}",
+      "est_tokens": "估算 tokens:  {count}",
+      "health_title": "### 🏥 系统健康",
+      "overall": "总体: {bar} **{score}/100**",
+      "assessment": "评估: {assessment}",
+      "constitution_title": "### ⚖️ 宪法",
+      "principles": "原则: **{total}** (🚫 {block} 拦截 | ⚠️ {warn} 警告 | 🔄 {auto} 自动)",
+      "version": "版本: v{version}",
+      "empty": "_开始使用工具以填充 CRSI 可解释性数据。_",
+      "filter_hint": "🔍 按工具过滤: `/crsi interpret <工具名>` (例如 `/crsi interpret Bash`)"
+    },
+    "crsi_red_team": {
+      "not_init": "Red-Team 需要 ConstitutionLoader 和 PreFlightChecker 均已初始化。",
+      "title": "## 🔴 CRSI 红队报告",
+      "score": "总体得分: **{score}/100**",
+      "metric": "| 指标 | 数量 |",
+      "metric_sep": "|------|------|",
+      "total_attacks": "| 总攻击数 | {count} |",
+      "blocked": "| 🛡️ 正确拦截 | {count} |",
+      "passed_through": "| 🔴 穿透（缺口） | {count} |",
+      "false_positives": "| ⚠️ 误报 | {count} |",
+      "by_principle": "### 按原则",
+      "gaps_title": "### 🔴 安全缺口（本应被拦截）",
+      "gap_tool": "  工具: `{tool}` → 参数: `{params}`",
+      "blocked_title": "### 🛡️ 成功拦截",
+      "caught_by": "{principle}: {desc} → 由 **{caught}** 捕获",
+      "all_blocked": "🎉 **所有攻击均被拦截！** SIS 自免疫系统完全正常运转。",
+      "good_coverage": "⚠️ 覆盖良好。请审查上述缺口，并向 `ai-guardrails.yml` 添加审计模式。",
+      "critical": "🔴 **检测到严重缺口。** 优先修复上述穿透的攻击。"
+    },
+    "dream": {
+      "not_init": "DreamEngine 未初始化。请确认 Mipham Code 版本 >= v0.34.0。",
+      "no_history": "🌙 尚未运行过 Auto-Dream。使用 `/dream` 手动触发首次梦境整合。",
+      "history_title": "## 🌙 Auto-Dream 历史",
+      "history_entry": "- **{time}**: {total} 行动 ({applied} 自动应用, {flagged} 标记审查)",
+      "done_title": "## 🌙 Auto-Dream 完成",
+      "integrate": "记忆整合: {before} → {after}",
+      "dedup": "- 去重: {count} 条",
+      "contradiction": "- 矛盾冲突: {count} 处 (需人工裁决)",
+      "merge": "- 合并: {count} 组",
+      "solidify": "- 模糊标记: {count} 条 (建议固化)",
+      "prune": "- 清理过期: {count} 条",
+      "review_hint": "⚠️  {count} 项待审查。使用 `/dream --aggressive` 自动应用所有操作。",
+      "clean": "✅ 记忆干净，无需整理。"
+    },
+    "constitution": {
+      "not_init": "ConstitutionLoader 未初始化。请确认 Mipham Code 版本 >= v0.34.0。",
+      "reload_title": "## ⚖️ 宪法已重新加载",
+      "version": "版本: **v{version}**",
+      "principles": "原则: **{count}**",
+      "path": "路径: `{path}`",
+      "view_title": "## ⚖️ Mipham 宪法",
+      "view_summary": "版本: **v{version}** | 原则: **{count}** | 路径: `{path}`",
+      "scope": "  作用域: `{scope}`",
+      "tools": "  工具: {tools}",
+      "reload_hint": "🔧 `/constitution reload` — 重新加载（修改 ai-guardrails.yml 后使用）",
+      "edit_hint": "📝 编辑: `vi ~/.mipham/ai-guardrails.yml`",
+      "reset_hint": "🗑️  重置: 删除 `~/.mipham/ai-guardrails.yml` 后执行 `/constitution reload`",
+      "inspired": "*灵感来自 Anthropic 宪法 AI。Mipham 在运行时强制执行这些原则 — 每次行动都可审计。*"
+    },
+    "bug_report": {
+      "title": "## 🐛 Bug 报告",
+      "hint": "> 复制下面的报告并粘贴到你的 GitHub Issue 中。",
+      "env_title": "### 环境",
+      "mipham": "- **Mipham Code**: v{version}",
+      "session": "- **会话**: {id}",
+      "node": "- **Node**: {version}",
+      "platform": "- **平台**: {platform} {arch}",
+      "os": "- **操作系统**: {os}",
+      "provider": "- **提供商**: {provider}",
+      "model": "- **模型**: {model}",
+      "sigs_title": "### 活跃错误签名",
+      "sig_entry": "- `{id}`: {pattern} ({category}, {occurrences}次, {pct}% 成功率)",
+      "disabled_hooks": "### 已禁用的 Hooks",
+      "hook_entry": "- `{key}`: {failures} 次失败, 于 {time} 禁用",
+      "last_dream": "### 最近一次 Auto-Dream",
+      "ran_at": "- **运行于**: {time}",
+      "actions": "- **行动**: {total} ({applied} 已应用)",
+      "steps_title": "### 复现步骤",
+      "expected": "### 预期行为",
+      "actual": "### 实际行为",
+      "generated": "🤖 由 Mipham Code v{version} 生成"
+    },
+    "changelog": {
+      "title": "## 📋 变更日志",
+      "no_tags": "未找到版本标签。",
+      "current": "当前: **v{version}**",
+      "current_marker": " ← 当前",
+      "release_only": "  _(仅发布标签)_",
+      "details_unavailable": "  _(详情不可用)_",
+      "no_git": "无法读取 git 历史。请确认你位于 Mipham Code 仓库中。",
+      "full_history": "完整历史: `git log --oneline`"
     }
   },
   "ui": {

package/src/index.tsx

@@ -281,12 +281,6 @@ export async function runApp(options: RunOptions): Promise<void> {
     skillsLoader.loadExternal(config.skills.paths)
   }
 
-  // Inject skills system-reminder into system prompt for AI auto-triggering
-  const skillsReminder = skillsLoader.buildSystemReminder()
-  if (skillsReminder) {
-    instructions.setSkillsReminder(skillsReminder)
-  }
-
   // Initialize plugin manager
   const pluginManager = new PluginManager()
 
@@ -327,8 +321,6 @@ export async function runApp(options: RunOptions): Promise<void> {
   // Phase 9 feature flags (all default true — opt-out via config)
   const features = config.features || {}
   const adaptiveThresholds = features.context?.adaptiveThresholds !== false
-  // gated via TokenCounter — set to false to fall back to chars/4 heuristic
-  const _useRealTokenizer = features.context?.useRealTokenizer !== false
 
   const context = new ContextManager({
     maxTokens: contextMaxTokens,
@@ -372,9 +364,13 @@ export async function runApp(options: RunOptions): Promise<void> {
   if (context.getMessageCount() === 0) {
     const basePrompt = instructions.buildSystemPrompt(config.permission as string)
     const memoryReminder = loadSessionMemories(basePrompt)
+    const skillsReminder = skillsLoader.buildSystemReminder(basePrompt)
 
     // Inject previous session summary for AI continuity
     let prompt = basePrompt
+    if (skillsReminder) {
+      prompt = `${prompt}\n\n${skillsReminder}`
+    }
     if (memoryReminder) {
       prompt = `${prompt}\n\n${memoryReminder}`
     }
@@ -524,6 +520,12 @@ export async function runApp(options: RunOptions): Promise<void> {
     engine.getPermission().setRestrictions(config.permissionRestrictions)
   }
 
+  // Apply user-defined permission rules (allow/deny) — wire the rule system into runtime
+  if (config.permissionRules) {
+    for (const rule of config.permissionRules.allow ?? []) engine.getPermission().allow(rule)
+    for (const rule of config.permissionRules.deny ?? []) engine.getPermission().deny(rule)
+  }
+
   // Initialize agent registry and load plugin agents/skills/MCP/hooks
   const agentRegistry = new AgentRegistry()
   agentRegistry.loadUserAgents()

package/src/mcp/token-store.ts

@@ -8,13 +8,8 @@ import {
   chmodSync,
 } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
 import { homedir } from 'node:os'
-
-const ALGORITHM = 'aes-256-gcm'
-const IV_LENGTH = 16
-const AUTH_TAG_LENGTH = 16
-const KEY_LENGTH = 32
+import { encrypt, decrypt, getCredentialKey } from '../config/credential-crypto'
 
 interface TokenData {
   accessToken: string
@@ -24,43 +19,13 @@ interface TokenData {
   scopes?: string[]
 }
 
-function getEncryptionKey(keyPath: string): Buffer {
-  if (existsSync(keyPath)) {
-    return readFileSync(keyPath)
-  }
-  const key = randomBytes(KEY_LENGTH)
-  mkdirSync(dirname(keyPath), { recursive: true })
-  writeFileSync(keyPath, key)
-  chmodSync(keyPath, 0o400)
-  return key
-}
-
-function encrypt(plaintext: string, key: Buffer): string {
-  const iv = randomBytes(IV_LENGTH)
-  const cipher = createCipheriv(ALGORITHM, key, iv)
-  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()])
-  const authTag = cipher.getAuthTag()
-  return Buffer.concat([iv, authTag, encrypted]).toString('base64')
-}
-
-function decrypt(ciphertext: string, key: Buffer): string {
-  const buf = Buffer.from(ciphertext, 'base64')
-  const iv = buf.subarray(0, IV_LENGTH)
-  const authTag = buf.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH)
-  const encrypted = buf.subarray(IV_LENGTH + AUTH_TAG_LENGTH)
-  const decipher = createDecipheriv(ALGORITHM, key, iv)
-  decipher.setAuthTag(authTag)
-  return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf-8')
-}
-
 export class TokenStore {
   private key: Buffer
   private storeDir: string
 
   constructor(storeDir?: string) {
     this.storeDir = storeDir || join(homedir(), '.mipham', 'mcp-tokens')
-    const keyPath = join(dirname(this.storeDir), '.mcp-key')
-    this.key = getEncryptionKey(keyPath)
+    this.key = getCredentialKey(dirname(this.storeDir))
   }
 
   save(serverName: string, data: TokenData): void {

package/src/shared/package-info.ts

@@ -9,7 +9,7 @@
 export const PACKAGE_NAME = '@miphamai/cli' as const
 
 /** 当前发布版本 */
-export const PACKAGE_VERSION = '0.50.0' as const
+export const PACKAGE_VERSION = '0.52.0' as const
 
 /** npm install 全局安装命令 */
 export const NPM_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}` as const

package/src/shared/types.ts

@@ -133,6 +133,8 @@ export interface MiphamConfig {
   permission: ToolPermission
   /** Org-level permission restrictions (forbiddenModes, maxAllowedMode). */
   permissionRestrictions?: PermissionRestrictions
+  /** User-defined permission rules (allow/deny patterns), wired into the runtime PermissionSystem. */
+  permissionRules?: { allow?: string[]; deny?: string[] }
   providers: ProviderConfig[]
   skills?: { paths: string[]; mcpServers: McpServerConfig[] }
   marketplace?: {
@@ -149,7 +151,7 @@ export interface MiphamConfig {
 
 export interface FeatureFlags {
   mcp: { oauthEnabled: boolean }
-  context: { useRealTokenizer: boolean; adaptiveThresholds: boolean }
+  context: { adaptiveThresholds: boolean }
 }
 
 export interface CrsiConfig {
@@ -481,8 +483,8 @@ export interface SkillDefinition {
   allowedTools?: string[]
   /** When true, the skill is NOT shown in system-reminder for AI auto-triggering */
   disableModelInvocation?: boolean
-  /** When true, users can invoke this skill directly via /<name> */
-  userInvocable?: boolean
+  /** External command-line binaries the skill requires (frontmatter: requires-bins). */
+  requiresBins?: string[]
   /** The markdown body content of the skill file (instructions for the AI to follow). */
   body?: string
 }

package/src/skills/bin-check.ts

@@ -0,0 +1,40 @@
+import { existsSync } from 'node:fs'
+import { join, delimiter } from 'node:path'
+
+// Windows executable extensions (subset of PATHEXT) probed for bare names.
+const WINDOWS_EXECUTABLES = ['.exe', '.cmd', '.bat', '.com']
+
+/**
+ * Check whether a command-line binary is available on the system PATH.
+ * Accepts an explicit `pathVar` for testability; defaults to `process.env.PATH`.
+ * A value containing a path separator is treated as an explicit path and
+ * checked for existence directly.
+ */
+export function isBinAvailable(bin: string, pathVar: string = process.env.PATH || ''): boolean {
+  // Explicit path (absolute or relative) — check existence directly.
+  if (bin.includes('/') || bin.includes('\\')) {
+    return existsSync(bin)
+  }
+
+  const isWindows = process.platform === 'win32'
+  const names = isWindows ? WINDOWS_EXECUTABLES.map((ext) => bin + ext) : [bin]
+  const dirs = pathVar.split(delimiter).filter(Boolean)
+
+  for (const dir of dirs) {
+    for (const name of names) {
+      if (existsSync(join(dir, name))) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Return the subset of `bins` that are NOT available on PATH. An empty result
+ * means every required binary is present.
+ */
+export function checkRequiredBins(
+  bins: string[],
+  pathVar: string = process.env.PATH || '',
+): string[] {
+  return bins.filter((bin) => !isBinAvailable(bin, pathVar))
+}