@daweifu/capability-menu 0.1.0

package/lib/invoke.js

@@ -0,0 +1,299 @@
+/**
+ * Model-facing `meta_invoke` tool: unified execution/loading of capabilities.
+ *
+ * @module @daweifu/capability-menu (invoke plugin)
+ */
+import z from '@deepseek-ai/schemastery';
+import { CallId } from '@deepseek-ai/dsh-llm';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { isModelInvocable, renderSkillContent } from '@deepseek-ai/dsh-skill';
+import { SKILL_ID_PREFIX, skillNameOf } from "./registry.js";
+export const name = 'capability-menu-invoke';
+export const inject = ['meta', 'tools', 'skills'];
+/** Validate and default the tool configuration. */
+export const Config = z.object({
+    forwardMode: z.union(['direct', 'resolve']).default('direct'),
+});
+/**
+ * Register the `meta_invoke` tool.
+ *
+ * Dispatch is by `capability.kind`, not by id prefix (the id-prefix check is
+ * kept only as a defensive guard alongside the kind check).
+ *
+ * - Tools (`kind: 'tool'`, id `mcp__...`): forwards to the underlying server
+ *   call via the official `ctx.tools.execute` pipeline, preserving
+ *   `agent`/`signal`/parent lineage. `forwardMode: 'resolve'` instead returns
+ *   the target schema so the model can call the tool directly.
+ * - Skills (`kind: 'skill'`, id `skill:<name>`): loads the full skill
+ *   instructions and returns them as `<skill_content>` — no args, no script
+ *   execution (matches the existing `skill` tool semantics).
+ */
+export function apply(ctx, config = {}) {
+    const forwardMode = config.forwardMode ?? 'direct';
+    if (forwardMode !== 'direct' && forwardMode !== 'resolve') {
+        throw new Error(`forwardMode must be "direct" or "resolve", received "${String(forwardMode)}"`);
+    }
+    // Session-level dedup for loaded skills. Re-loading an already-injected
+    // skill only returns a short reminder instead of re-injecting the full
+    // instructions, saving tokens (mirrors synapse's `_loaded_skills`).
+    const loadedSkills = new Set();
+    /**
+     * Load a Progressive skill's full body. Progressive skills are indexed from
+     * the independent YAML catalog and may not be registered in `ctx.skills`; read
+     * the catalog entry's `path` (SKILL.md) directly and strip frontmatter to
+     * produce a `SkillDefinition`-compatible body.
+     */
+    const loadProgressiveSkill = async (name, capability, signal) => {
+        // If the skill is registered globally, prefer the registry's parser.
+        const registered = await ctx.skills.get(name, { signal }).catch(() => undefined);
+        if (registered !== undefined)
+            return registered;
+        const basePath = capability.origin.path;
+        if (basePath === undefined)
+            return undefined;
+        const { readFile } = await import('node:fs/promises');
+        const { resolve } = await import('node:path');
+        const markdownPath = resolve(process.cwd(), basePath, 'SKILL.md');
+        let text;
+        try {
+            text = await readFile(markdownPath, 'utf8');
+        }
+        catch (error) {
+            ctx.logger.warn(`meta_invoke: progressive skill "${name}" body not readable (${markdownPath}): ${String(error)}`);
+            return undefined;
+        }
+        const content = stripFrontmatter(text);
+        return {
+            name,
+            description: capability.description,
+            ...capability.whenToUse !== undefined ? { whenToUse: capability.whenToUse } : {},
+            invocation: { modelInvocable: true, userInvocable: false },
+            source: { type: 'local' },
+            provider: capability.origin.provider ?? 'progressive-catalog',
+            ...capability.origin.path !== undefined ? { path: resolve(process.cwd(), capability.origin.path) } : {},
+            resourceBase: { kind: 'directory', path: resolve(process.cwd(), basePath) },
+            content,
+        };
+    };
+    const tool = defineTool({
+        name: 'meta_invoke',
+        description: 'Execute a capability by its exact id (from meta_search), dispatching by capability kind. For tools (kind "tool", id starts with "mcp__"), forwards to the underlying server call with args. For skills (kind "skill", id starts with "skill:"), loads the full skill instructions and returns them as <skill_content> — no args needed.',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Capability id from meta_search, e.g. mcp__gongfeng__create_issue or skill:frontend-design.' },
+            args: { type: 'json', description: 'Arguments forwarded to a tool; ignored for skills.' },
+        },
+        output: {
+            schema: {
+                oneOf: [
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            ok: { type: 'boolean', required: true, const: true },
+                            kind: { type: 'string', required: true, const: 'mcp' },
+                            id: { type: 'string', required: true },
+                            detail: {
+                                type: 'object',
+                                required: true,
+                                additionalProperties: false,
+                                properties: {
+                                    forwarded: { type: 'boolean', required: true, const: true },
+                                    target: { type: 'string', required: true },
+                                    content: { type: 'array', required: true, items: { type: 'json' } },
+                                },
+                            },
+                        },
+                    },
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            ok: { type: 'boolean', required: true, const: true },
+                            kind: { type: 'string', required: true, const: 'skill' },
+                            id: { type: 'string', required: true },
+                            detail: {
+                                type: 'object',
+                                required: true,
+                                additionalProperties: false,
+                                properties: {
+                                    name: { type: 'string', required: true },
+                                    provider: { type: 'string', required: true },
+                                    resourceBase: { type: 'json' },
+                                    content: { type: 'string', required: true },
+                                },
+                            },
+                        },
+                    },
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            ok: { type: 'boolean', required: true, const: true },
+                            kind: { type: 'string', required: true, const: 'resolve' },
+                            id: { type: 'string', required: true },
+                            detail: {
+                                type: 'object',
+                                required: true,
+                                additionalProperties: false,
+                                properties: {
+                                    target: { type: 'string', required: true },
+                                    kind: { type: 'string', required: true },
+                                    name: { type: 'string', required: true },
+                                    description: { type: 'string', required: true },
+                                    parameters: { type: 'json', required: true },
+                                },
+                            },
+                        },
+                    },
+                ],
+            },
+            render: (_args, value) => {
+                const result = value;
+                if (result.ok && result.kind === 'skill') {
+                    return [{ type: 'text', text: renderSkillContent(result.detail) }];
+                }
+                return [{ type: 'text', text: JSON.stringify(value) }];
+            },
+        },
+        async execute(args, exec) {
+            const id = args.id.trim();
+            // Blocked capabilities are a hard deny at the execution surface: the
+            // registry keeps them indexed so the management UI can list them, but the
+            // model can never reach a blocked capability through meta_invoke.
+            const policy = ctx.get('capabilityPolicy');
+            if (policy?.isBlockedCapability(id)) {
+                throw new Error(`meta_invoke: capability "${id}" is blocked and cannot be invoked`);
+            }
+            const capability = ctx.meta.get(id);
+            if (capability === undefined) {
+                throw new Error(`meta_invoke: capability "${id}" is unknown or no longer available`);
+            }
+            // Tool: forward to the underlying MCP server call (or resolve its schema).
+            if (capability.kind === 'tool' && id.startsWith('mcp__')) {
+                // Resolve the definition on the GLOBAL view (no agent scope) so a
+                // Progressive tool hidden from the caller's exposure is still addressable.
+                const definition = ctx.tools.get(capability.name);
+                if (definition === undefined) {
+                    throw new Error(`meta_invoke: tool "${capability.name}" is not available`);
+                }
+                if (forwardMode === 'resolve') {
+                    return {
+                        ok: true,
+                        kind: 'resolve',
+                        id,
+                        detail: {
+                            target: capability.name,
+                            kind: 'tool',
+                            name: definition.name,
+                            description: definition.description,
+                            parameters: definition.parameters,
+                        },
+                    };
+                }
+                // Nested execution through the official pipeline. The parent token marks
+                // this as a transport sub-dispatch so code-mode collapse rules treat it
+                // like a nested SDK call, and `tools/result` observers can attribute the
+                // outcome to the target capability.
+                // Do NOT pass `agent` — `ctx.tools.execute` resolves through the
+                // caller's `view.visible`, so passing an agent whose projection hid the
+                // Progressive tool would surface `UNKNOWN_TOOL`. Executing on the global view
+                // keeps Progressive tools runnable; the target tool's own guards still apply
+                // (no permission bypass — see README).
+                const result = await ctx.tools.execute({
+                    callId: CallId(`${exec.callId}:meta:${id}`),
+                    name: capability.name,
+                    arguments: args.args,
+                    signal: exec.signal,
+                    parent: exec.token,
+                });
+                if (result.isError) {
+                    const message = result.content.map(block => block.type === 'text' ? block.text : `[${block.type} content]`).join('\n');
+                    throw new Error(message || `meta_invoke: ${capability.name} failed`);
+                }
+                return {
+                    ok: true,
+                    kind: 'mcp',
+                    id,
+                    detail: {
+                        forwarded: true,
+                        target: capability.name,
+                        content: result.content,
+                    },
+                };
+            }
+            // Skill: load the full instructions.
+            if (capability.kind === 'skill' && id.startsWith(SKILL_ID_PREFIX)) {
+                const name = skillNameOf(id);
+                // Already loaded this session → return a short reminder, no re-injection.
+                if (loadedSkills.has(name)) {
+                    return {
+                        ok: true,
+                        kind: 'skill',
+                        id,
+                        detail: {
+                            name,
+                            provider: capability.origin.provider,
+                            content: `Skill "${name}" is already loaded in this conversation. Read the <skill_content> above and follow it.`,
+                        },
+                    };
+                }
+                const lookup = {
+                    cwd: exec.agent?.session.header.cwd,
+                    signal: exec.signal,
+                    scope: exec.agent,
+                };
+                let skill = await ctx.skills.get(name, lookup).catch(() => undefined);
+                // Progressive skills are indexed from the independent YAML catalog; they may
+                // not be registered in the session skill registry. Fall back to reading
+                // the catalog entry's path (or the catalog-provided name lookup) so the
+                // full SKILL.md can still be loaded on demand.
+                if (skill === undefined) {
+                    skill = await loadProgressiveSkill(name, capability, exec.signal);
+                }
+                if (skill === undefined) {
+                    throw new Error(`meta_invoke: skill "${name}" is unknown or no longer available`);
+                }
+                if (!isModelInvocable(skill)) {
+                    throw new Error(`meta_invoke: skill "${name}" is not available for model invocation`);
+                }
+                loadedSkills.add(name);
+                return {
+                    ok: true,
+                    kind: 'skill',
+                    id,
+                    detail: {
+                        name: skill.name,
+                        provider: skill.provider,
+                        ...skill.resourceBase !== undefined ? { resourceBase: { ...skill.resourceBase } } : {},
+                        content: skill.content,
+                    },
+                };
+            }
+            throw new Error(`meta_invoke: capability id "${id}" has an unrecognized kind`);
+        },
+        presentCall(args) {
+            return {
+                card: 'generic',
+                title: `Execute capability ${args.id}`,
+                kind: args.id.startsWith('skill:') ? 'read' : 'other',
+                rawInput: args.id,
+            };
+        },
+    });
+    ctx.tools.register(tool);
+}
+/**
+ * Strip leading YAML frontmatter (`---\n...\n---`) from a raw SKILL.md body,
+ * returning the remaining markdown. Falls back to the raw text when no
+ * frontmatter delimiter is present.
+ */
+export function stripFrontmatter(markdown) {
+    const text = markdown.startsWith('\uFEFF') ? markdown.slice(1) : markdown;
+    if (!text.startsWith('---'))
+        return text;
+    const end = text.indexOf('\n---', 3);
+    if (end === -1)
+        return text;
+    return text.slice(end + 4).replace(/^\n+/, '');
+}
+//# sourceMappingURL=invoke.js.map

package/lib/policy.js

@@ -0,0 +1,264 @@
+/**
+ * Exposed / Progressive / Blocked capability projection policy for the DeepSeek
+ * Harness.
+ *
+ * @module @daweifu/capability-menu (policy plugin)
+ */
+import z from '@deepseek-ai/schemastery';
+import { serverNameOf } from "./registry.js";
+/** Validate and default the policy configuration. */
+export const Config = z.object({
+    tools: z.object({
+        exposed: z.array(z.string()).default([]),
+        progressive: z.array(z.string()).default([]),
+        blocked: z.array(z.string()).default([]),
+    }),
+    skills: z.object({
+        exposed: z.array(z.string()).default([]),
+        progressive: z.array(z.string()).default([]),
+        blocked: z.array(z.string()).default([]),
+    }),
+    metaTools: z.array(z.string()).default(['meta_search', 'meta_invoke']),
+    // schemastery object properties are optional-by-default; no `.optional()` needed.
+    progressiveSkillCatalog: z.string(),
+});
+export const DEFAULT_META_TOOLS = ['meta_search', 'meta_invoke'];
+/**
+ * Convert a user-facing rule string into a normalized {@link PolicyRule}.
+ * - `server:<name>` → server-targeted rule (`target: 'server'`).
+ * - `server:<name>:*` → server-targeted glob over that server's tools.
+ * - contains `*` → glob (target `id`).
+ * - otherwise → literal exact name.
+ */
+export function parseRule(rule) {
+    const trimmed = rule.trim();
+    const serverPrefix = 'server:';
+    if (trimmed.startsWith(serverPrefix)) {
+        const rest = trimmed.slice(serverPrefix.length);
+        // `server:<name>:*` → glob over the whole server.
+        if (rest.endsWith(':*')) {
+            return { wildcard: true, pattern: rest.slice(0, -2), target: 'server', kind: 'tool' };
+        }
+        return { wildcard: false, pattern: rest, target: 'server', kind: 'tool' };
+    }
+    return {
+        wildcard: trimmed.includes('*'),
+        pattern: trimmed,
+        target: 'id',
+    };
+}
+/** Compile a `*`-glob into a RegExp (escaped, `*` → `.*`). */
+export function compileGlob(pattern) {
+    const escaped = pattern
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/\\\*/g, '.*');
+    return new RegExp(`^${escaped}$`);
+}
+/** Compile a {@link CapabilitySetConfig} into fast-matchable rules. */
+export function compileSet(set = {}) {
+    return {
+        exposed: (set.exposed ?? []).map(parseRule),
+        progressive: (set.progressive ?? []).map(parseRule),
+        blocked: (set.blocked ?? []).map(parseRule),
+    };
+}
+function ruleMatches(rule, target) {
+    if (rule.kind !== undefined && rule.kind !== target.ruleKind)
+        return false;
+    if (rule.target === 'id') {
+        if (!rule.wildcard) {
+            // An exact rule matches the full id OR the bare name (e.g. `debugging`
+            // matches `skill:debugging`, `bash` matches the harness-native tool
+            // `bash` whose public name is its bare name).
+            return rule.pattern === target.id || rule.pattern === target.name;
+        }
+        return compileGlob(rule.pattern).test(target.id);
+    }
+    // server-targeted
+    if (target.server === undefined)
+        return false;
+    if (!rule.wildcard)
+        return rule.pattern === target.server;
+    return compileGlob(rule.pattern).test(target.server);
+}
+/**
+ * Classify a capability against compiled rules. Priority (hit stops the walk):
+ * blocked-exact > blocked-wildcard > exposed-exact > exposed-wildcard >
+ * progressive-exact > progressive-wildcard > default (exposed). `blocked`
+ * is a control decision, so it beats an explicit `exposed` rule.
+ */
+export function classify(compiled, target, metaTools = DEFAULT_META_TOOLS) {
+    const meta = metaTools instanceof Set ? metaTools : new Set(metaTools);
+    const id = target.id;
+    // metaTools can never be Progressive/Blocked for tools.
+    if (target.kind === 'tool' && meta.has(id))
+        return 'exposed';
+    for (const rule of compiled.blocked) {
+        if (!rule.wildcard && ruleMatches(rule, target))
+            return 'blocked';
+    }
+    for (const rule of compiled.blocked) {
+        if (rule.wildcard && ruleMatches(rule, target))
+            return 'blocked';
+    }
+    for (const rule of compiled.exposed) {
+        if (!rule.wildcard && ruleMatches(rule, target))
+            return 'exposed';
+    }
+    for (const rule of compiled.exposed) {
+        if (rule.wildcard && ruleMatches(rule, target))
+            return 'exposed';
+    }
+    for (const rule of compiled.progressive) {
+        if (!rule.wildcard && ruleMatches(rule, target))
+            return 'progressive';
+    }
+    for (const rule of compiled.progressive) {
+        if (rule.wildcard && ruleMatches(rule, target))
+            return 'progressive';
+    }
+    return 'exposed';
+}
+/** True when any rule in the list matches the target (used for fail-loud validation). */
+function anyRuleMatches(rules, target) {
+    return rules.some(rule => ruleMatches(rule, target));
+}
+const CLASS_LABELS = {
+    exposed: 'Exposed · 常驻（直接调用）',
+    progressive: 'Progressive · 按需（目录渐进加载）',
+    blocked: 'Blocked · 禁用',
+};
+/**
+ * Build the projection listener for one assembly: keep only Exposed tools plus
+ * the mandatory meta tools.
+ */
+export function projectAssemblyTools(assembly, service) {
+    const kept = assembly.tools.filter(tool => service.isExposedTool(tool.name));
+    if (kept.length === assembly.tools.length)
+        return assembly;
+    return { ...assembly, tools: kept };
+}
+/** Build the policy plugin. */
+export const name = 'capability-menu-policy';
+// The policy needs `meta` (the registry sibling) for classifyAll(); `tools` /
+// `skills` are injected purely for startup ordering — projection itself runs on
+// the `system-prompt/assemble` chain, not through the registries. The bundle
+// mounts registry before policy, so `meta` is always available in practice.
+export const inject = ['meta', 'tools', 'skills'];
+export function apply(ctx, config = {}) {
+    // Mutable runtime state so the management surface (能力菜单) can live-update
+    // the policy without a reload.
+    let current = { ...config };
+    let metaTools = [...(config.metaTools ?? DEFAULT_META_TOOLS)];
+    let metaToolSet = new Set(metaTools);
+    let toolCompiled;
+    let skillCompiled;
+    const recompile = () => {
+        const toolRules = compileSet(current.tools);
+        const skillRules = compileSet(current.skills);
+        // Normalize tool/skill rule kinds for matching.
+        toolCompiled = {
+            exposed: toolRules.exposed.map(rule => ({ ...rule, kind: 'tool' })),
+            progressive: toolRules.progressive.map(rule => ({ ...rule, kind: 'tool' })),
+            blocked: toolRules.blocked.map(rule => ({ ...rule, kind: 'tool' })),
+        };
+        skillCompiled = {
+            exposed: skillRules.exposed.map(rule => ({ ...rule, kind: 'skill' })),
+            progressive: skillRules.progressive.map(rule => ({ ...rule, kind: 'skill' })),
+            blocked: skillRules.blocked.map(rule => ({ ...rule, kind: 'skill' })),
+        };
+        // Meta tools are the control-plane escape hatch: blocking one is a
+        // misconfiguration that must fail loud, never silently disable the surface.
+        for (const name of metaTools) {
+            const target = { id: name, name, server: serverNameOf(name), kind: 'tool', ruleKind: 'tool' };
+            if (anyRuleMatches(toolCompiled.blocked, target)) {
+                throw new Error(`meta tool "${name}" cannot be blocked; remove it from tools.blocked`);
+            }
+        }
+    };
+    recompile();
+    const service = {
+        classifyTool(name) {
+            const server = serverNameOf(name);
+            return classify(toolCompiled, { id: name, name, server, kind: 'tool', ruleKind: 'tool' }, metaToolSet);
+        },
+        classifySkill(name) {
+            return classify(skillCompiled, { id: `skill:${name}`, name, kind: 'skill', ruleKind: 'skill' }, new Set());
+        },
+        classifyCapability(id) {
+            if (id.startsWith('skill:'))
+                return service.classifySkill(id.slice('skill:'.length));
+            return service.classifyTool(id);
+        },
+        isExposedTool(name) {
+            return service.classifyTool(name) === 'exposed';
+        },
+        isExposedSkill(name) {
+            return service.classifySkill(name) === 'exposed';
+        },
+        isProgressiveTool(name) {
+            return service.classifyTool(name) === 'progressive';
+        },
+        isProgressiveSkill(name) {
+            return service.classifySkill(name) === 'progressive';
+        },
+        isBlockedTool(name) {
+            return service.classifyTool(name) === 'blocked';
+        },
+        isBlockedSkill(name) {
+            return service.classifySkill(name) === 'blocked';
+        },
+        isBlockedCapability(id) {
+            return service.classifyCapability(id) === 'blocked';
+        },
+        metaTools() {
+            return metaTools;
+        },
+        toolRules() {
+            return toolCompiled;
+        },
+        skillRules() {
+            return skillCompiled;
+        },
+        getConfig() {
+            return { ...current };
+        },
+        updateConfig(partial) {
+            current = { ...current, ...partial };
+            if (partial.metaTools !== undefined) {
+                metaTools = [...(partial.metaTools ?? DEFAULT_META_TOOLS)];
+                metaToolSet = new Set(metaTools);
+            }
+            recompile();
+        },
+        classifyAll() {
+            // The registry default maxResults (20) would truncate the management
+            // surface: enumerate every indexed capability, not just the top-20.
+            return ctx.meta.search({ maxResults: Number.MAX_SAFE_INTEGER }).map(summary => {
+                const cls = service.classifyCapability(summary.id);
+                const mandatory = summary.kind === 'tool' && metaToolSet.has(summary.id);
+                return {
+                    id: summary.id,
+                    kind: summary.kind,
+                    name: summary.name,
+                    ...summary.server !== undefined ? { server: summary.server } : {},
+                    class: cls,
+                    classLabel: CLASS_LABELS[cls],
+                    mandatory,
+                };
+            });
+        },
+    };
+    // Project the model-visible tool list. This runs on the projection chain only
+    // (system-prompt/assemble); the execution chain (ctx.tools.execute) is
+    // untouched, so Progressive tools remain executable via meta_invoke. Skills
+    // keep the dsh-native `<available_skills>` catalog, which is the Exposed
+    // surface; catalog-level skill filtering needs an upstream `dsh-tool-skill`
+    // filter hook (out of bundle scope).
+    ctx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+        const resolved = await next();
+        return projectAssemblyTools(resolved, service);
+    });
+    ctx.provide('capabilityPolicy', service);
+}
+//# sourceMappingURL=policy.js.map