@qodo/sdk 0.13.3 → 2.0.0-next.0

package/dist/skills/mcp/server.js

@@ -0,0 +1,841 @@
+/**
+ * `qodo-skills` MCP server implementation.
+ *
+ * Three tools, all `autoApproved: true`: `list_skills`, `get_skill`,
+ * `get_skill_file`. The server is a thin facade over a `SkillsManager`
+ * — the heavy lifting (catalog walk, parsing, validation, rendering) lives
+ * in the manager. The server owns:
+ *
+ *   - Tool-routing (which handler runs for which `tool_name`).
+ *   - In-memory caches keyed by `<fqn>` + `<fqn> + <rel-path>`.
+ *   - Path validation for `get_skill_file` (see `path.ts`).
+ *   - Telemetry emission via the manager's `forwardEvents` sink.
+ *   - Structured error responses on the `isError: true` envelope.
+ *
+ * Integration: the SDK has no `InternalMCPBaseServer` interface. The
+ * integration shape is `McpInProcessHandler` from `QarRegistryClient`
+ * (`(req: { tool_name, arguments }) => Promise<...>`); the
+ * `QodoSkillsMcpServer` class is invoked via the {@link asMcpHandler}
+ * adapter. The SDK ships zero built-in MCPs by default — this server
+ * auto-registers via `client.qar.registerMcp('qodo-skills',
+ * { transport: 'sdk', handler })` when `ClientOptions.skills` is
+ * provided. Reach the registered config via
+ * `client.qar.getMcp('qodo-skills')`; the server instance itself is
+ * owned by `QodoClient`.
+ *
+ * Caches are cleared on {@link QodoSkillsMcpServer.dispose}.
+ */
+import { promises as fs, realpathSync as fsRealpathSync } from 'node:fs';
+import { SKILL_FILE_HARD_BYTES } from '../types.js';
+import { activationFailureMessage, capAgentField, lookupFromSnapshot, resolveActivationGraph, } from '../activation.js';
+import { preprocessBody } from '../preprocess.js';
+import { resolveSkillFilePath, SkillPathError } from './path.js';
+import { parseArgv, substituteWithArgumentsTrailer } from '../substitute.js';
+import { LIST_SKILLS_DEFAULT_LIMIT } from './types.js';
+// 256 KB — mirrors the `SKILL_FILE_HARD_BYTES` cap on the SKILL.md side.
+// Same number, deliberate: a supporting file cannot exceed what the skill
+// itself can be, so the cap is a single constant the operator sees in both
+// places.
+const FILE_HARD_BYTES = SKILL_FILE_HARD_BYTES;
+/**
+ * Extension → MIME map for `get_skill_file`. Anything not listed falls
+ * back to `application/octet-stream`; non-image binary returns render
+ * as a descriptive marker (`[binary file: N bytes, <mime>. Decode
+ * externally.]`), NOT raw base64.
+ *
+ * The text set covers what skill authors actually ship: markdown,
+ * source code, structured data. Images are a separate bucket so the
+ * MCP envelope can use the `image` content type.
+ */
+const TEXT_EXTENSIONS = new Map([
+    ['.md', 'text/markdown'],
+    ['.markdown', 'text/markdown'],
+    ['.txt', 'text/plain'],
+    ['.text', 'text/plain'],
+    ['.json', 'application/json'],
+    ['.yaml', 'application/yaml'],
+    ['.yml', 'application/yaml'],
+    ['.toml', 'application/toml'],
+    ['.xml', 'application/xml'],
+    ['.html', 'text/html'],
+    ['.htm', 'text/html'],
+    ['.css', 'text/css'],
+    ['.js', 'text/javascript'],
+    ['.mjs', 'text/javascript'],
+    ['.cjs', 'text/javascript'],
+    ['.ts', 'text/typescript'],
+    ['.tsx', 'text/typescript'],
+    ['.jsx', 'text/javascript'],
+    ['.py', 'text/x-python'],
+    ['.rb', 'text/x-ruby'],
+    ['.sh', 'text/x-shellscript'],
+    ['.bash', 'text/x-shellscript'],
+    ['.zsh', 'text/x-shellscript'],
+    ['.go', 'text/x-go'],
+    ['.rs', 'text/x-rust'],
+    ['.c', 'text/x-c'],
+    ['.h', 'text/x-c'],
+    ['.cpp', 'text/x-c++'],
+    ['.hpp', 'text/x-c++'],
+    ['.java', 'text/x-java'],
+    ['.kt', 'text/x-kotlin'],
+    ['.swift', 'text/x-swift'],
+    ['.sql', 'application/sql'],
+]);
+const IMAGE_EXTENSIONS = new Map([
+    ['.png', 'image/png'],
+    ['.jpg', 'image/jpeg'],
+    ['.jpeg', 'image/jpeg'],
+    ['.gif', 'image/gif'],
+    ['.webp', 'image/webp'],
+    ['.bmp', 'image/bmp'],
+    ['.svg', 'image/svg+xml'],
+]);
+/** The MCP tool names the server routes. */
+export const QODO_SKILLS_TOOL_NAMES = ['list_skills', 'get_skill', 'get_skill_file'];
+// Projected wire-side tool defs live in a platform-neutral module so
+// the Node and browser builds source identical schemas. Re-exported
+// here for compatibility with the original barrel-import shape.
+export { qodoSkillsFunctionToolDefs } from './wireDefs.js';
+/**
+ * Server class for the three `qodo-skills` MCP tools. Construct one per
+ * `QodoClient` instance; the SDK auto-wires it through
+ * {@link QodoClient.constructor} when `ClientOptions.skills` is configured.
+ */
+export class QodoSkillsMcpServer {
+    skills;
+    bodyCache = new Map();
+    fileCache = new Map();
+    /**
+     * Shared with `SkillsManager.internalActiveFqns` so caller-pin
+     * activation and LLM-driven activation surface in one place
+     * (`client.skills.getActiveSkills()` /
+     * `client.skillsMcpServer.loadedSkillFqns`). The MCP server still owns
+     * the body / file caches it manages, but it does NOT own the active
+     * set — the manager does.
+     */
+    activeFqns;
+    emit;
+    /**
+     * Resolver for ambient substitution context. Wired in by `QodoClient` so
+     * each `get_skill` invocation sees the consumer's session ID, the active
+     * effort level, and the current `${QODO_SKILL_DIR}` (= the skill's own
+     * canonical path). When undefined, those envvar substitutions stay literal.
+     */
+    resolveContext;
+    constructor(skills, opts) {
+        this.skills = skills;
+        this.emit = opts?.emit;
+        this.activeFqns = skills.internalActiveFqns;
+        this.resolveContext = opts?.resolveContext;
+    }
+    /**
+     * The set of skill FQNs whose body has been loaded into the current run.
+     * Surfaces for testing + for forward-looking trust-tier middleware that
+     * needs to know which skills' `allowed-tools` should be in scope.
+     */
+    get loadedSkillFqns() {
+        return [...this.activeFqns];
+    }
+    /** Bytes currently held in the body cache. Useful for memory-pressure tests. */
+    get cachedBodyBytes() {
+        let total = 0;
+        for (const entry of this.bodyCache.values())
+            total += entry.bytes;
+        return total;
+    }
+    /**
+     * Drop the in-memory caches and active-skill set. Idempotent. Called by
+     * `QodoClient.disconnect()` so the next `connect()` starts cold.
+     *
+     * The active set is shared with `SkillsManager.internalActiveFqns`;
+     * clearing here implicitly clears the manager's surface too — both
+     * `client.skills.getActiveSkills()` and `client.skillsMcpServer.loadedSkillFqns`
+     * return empty after dispose.
+     */
+    dispose() {
+        this.bodyCache.clear();
+        this.fileCache.clear();
+        this.activeFqns.clear();
+    }
+    /**
+     * Route a call by `tool_name` to the matching handler. Unknown names
+     * return an MCP error envelope. The handler signature matches the
+     * `McpInProcessHandler` contract so the same instance is registered via
+     * `client.qar.registerMcp(name, { transport: 'sdk', handler })`.
+     */
+    async callTool(toolName, args) {
+        switch (toolName) {
+            case 'list_skills':
+                return this.handleListSkills(args);
+            case 'get_skill':
+                return this.handleGetSkill(args);
+            case 'get_skill_file':
+                return this.handleGetSkillFile(args);
+            default:
+                return errorEnvelope(`unknown tool: ${toolName}. Available: ${QODO_SKILLS_TOOL_NAMES.join(', ')}.`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // list_skills
+    // ---------------------------------------------------------------------
+    async handleListSkills(args) {
+        const includeAllVersions = args.includeAllVersions === true;
+        const limit = typeof args.limit === 'number' && Number.isFinite(args.limit) && args.limit > 0
+            ? Math.floor(args.limit)
+            : LIST_SKILLS_DEFAULT_LIMIT;
+        const offset = typeof args.offset === 'number' && Number.isFinite(args.offset) && args.offset >= 0
+            ? Math.floor(args.offset)
+            : 0;
+        const query = typeof args.query === 'string' && args.query.length > 0 ? args.query : undefined;
+        const all = await this.skills.list({ includeAllVersions });
+        const filtered = query !== undefined ? filterByQuery(all, query) : all;
+        const total = filtered.length;
+        const window = filtered.slice(offset, offset + limit);
+        const entries = window.map((skill) => toListEntry(skill));
+        const response = {
+            total,
+            shown: entries.length,
+            skills: entries,
+            truncated: offset + entries.length < total,
+        };
+        return successJsonEnvelope(response);
+    }
+    // ---------------------------------------------------------------------
+    // get_skill
+    // ---------------------------------------------------------------------
+    async handleGetSkill(args) {
+        if (typeof args.name !== 'string' || args.name.length === 0) {
+            return errorEnvelope('get_skill: `name` is required and must be a non-empty string');
+        }
+        const root = await this.skills.get(args.name);
+        if (root === null) {
+            this.emitTel({
+                kind: 'sdk.skill.invocation_denied',
+                skill: args.name,
+                reason: 'not_found',
+            });
+            return errorEnvelope(`Skill '${args.name}' not found in catalog. Use list_skills to discover available skills.`);
+        }
+        // `disable-model-invocation: true` is a gate, never overridden by
+        // LLM-driven activation. Caller-pin can override it (the SDK injects
+        // bodies eagerly in `TaskClient`); the model-driven path here cannot.
+        if (root.frontmatter['disable-model-invocation'] === true) {
+            this.emitTel({
+                kind: 'sdk.skill.invocation_denied',
+                skill: root.fqn,
+                reason: 'user_invocable_only',
+            });
+            return errorEnvelope(`Skill '${root.fqnNoVersion}' has disable-model-invocation: true. The user must invoke it directly.`);
+        }
+        // Third-party model-driven activation requires `trustedSources`
+        // opt-in. Caller-pin bypasses this gate (the SDK's `TaskClient` path
+        // handles that), but LLM-driven calls hit it.
+        if (!this.skills.isTrusted(root)) {
+            this.emitTel({
+                kind: 'sdk.skill.invocation_denied',
+                skill: root.fqn,
+                reason: 'third_party_without_trust',
+            });
+            return errorEnvelope(`Skill '${root.fqnNoVersion}' is third-party and its source is not in trustedSources. ` +
+                'Caller-pin the skill via `tasks.startWithAgent({ skills })` or add the source to ' +
+                '`SkillsConfig.trustedSources` to opt in.');
+        }
+        // Resolve the `requires:` chain with the depth / breadth / token
+        // caps applied + transitive trust gate. The shared activation
+        // pipeline emits structured failure events that the caller-pin path
+        // also uses.
+        const snapshot = await this.skills.discover();
+        const lookup = lookupFromSnapshot(snapshot.skills, this.skills);
+        const resolution = resolveActivationGraph(root, lookup);
+        if (resolution.outcome !== 'ok') {
+            // Emit the resolver-side structured event first so observers see
+            // exactly *why* the resolution failed, then the
+            // `invocation_denied` rollup keyed by reason.
+            this.emitResolverFailure(root, resolution);
+            const reason = mapResolverFailureToDeniedReason(resolution.outcome);
+            this.emitTel({
+                kind: 'sdk.skill.invocation_denied',
+                skill: root.fqn,
+                reason,
+            });
+            return errorEnvelope(activationFailureMessage(root, resolution));
+        }
+        // Argument substitution context. Args from the tool call
+        // apply only to the *root* skill (the LLM asks for `name` + `arguments`);
+        // transitive dependencies render with their own bodies untouched by the
+        // caller's args, but still honor envvar aliases.
+        const ambient = this.resolveContext !== undefined ? this.resolveContext() : {};
+        const rawArgs = normalizeArgumentsArg(args.arguments);
+        // Compose the body: deps first (so the parent body sees them), root last.
+        const texts = [];
+        for (const skill of resolution.graph.ordered) {
+            const cachedHit = this.bodyCache.has(skill.fqn);
+            if (!cachedHit) {
+                // Run `!command` preprocessing before caching. The cache
+                // key is the FQN — preprocessing is deterministic for a given
+                // (catalog snapshot + config) pair, so we cache the post-
+                // processed body verbatim. Operators wanting fresh executions
+                // each call can `dispose()` the server (clears the cache).
+                const preprocessed = await preprocessBody(skill.body, {
+                    skill,
+                    isTrusted: this.skills.isTrusted(skill),
+                    env: process.env,
+                }, this.skills.preprocessingConfig);
+                if (preprocessed.events.length > 0) {
+                    this.skills.forwardEvents(preprocessed.events);
+                }
+                const entry = {
+                    body: preprocessed.body,
+                    bytes: Buffer.byteLength(preprocessed.body, 'utf-8'),
+                    argsHash: '',
+                };
+                this.bodyCache.set(skill.fqn, entry);
+            }
+            const cached = this.bodyCache.get(skill.fqn);
+            // Root-only argument application; dependencies render without args
+            // so a transitively-included skill body cannot consume the parent's
+            // caller-supplied args.
+            const isRoot = skill.fqn === resolution.graph.root.fqn;
+            const ctx = {
+                skill: skill.fqn,
+                ...(isRoot && rawArgs !== undefined ? { argumentsText: rawArgs.text, argv: rawArgs.argv } : {}),
+                named: skill.frontmatter.arguments,
+                skillDir: skill.path,
+                ...(ambient.sessionId !== undefined ? { sessionId: ambient.sessionId } : {}),
+                ...(ambient.effort !== undefined ? { effort: ambient.effort } : {}),
+            };
+            const substituted = substituteWithArgumentsTrailer(cached.body, ctx);
+            this.emitSubstitutionWarnings(skill.fqn, substituted.warnings);
+            const header = `<!-- qodo-skill: ${skill.fqn} -->`;
+            texts.push(`${header}\n${substituted.text.trim()}`);
+            const newlyActive = !this.activeFqns.has(skill.fqn);
+            this.activeFqns.add(skill.fqn);
+            this.emitTel({
+                kind: 'sdk.skill.loaded',
+                skill: skill.fqn,
+                bytes: cached.bytes,
+                cached: cachedHit,
+            });
+            // Emit `sdk.skill.activated` once per fresh activation (not on
+            // cache hits). Forwarded through `forwardEvents` since the event
+            // kind isn't in the narrow `QodoSkillsMcpEvent` MCP alias.
+            if (newlyActive) {
+                this.skills.forwardEvents([
+                    {
+                        kind: 'sdk.skill.activated',
+                        skill: skill.fqn,
+                        source: 'llm',
+                        tier: skill.trustTier,
+                    },
+                ]);
+                // Surface `allowed-tools` intent at LLM-driven activation time
+                // too. Trusted → applied; third-party → advisory (the trust
+                // gate above means we only reach here for trusted skills, so
+                // this is always `applied` in this branch — kept here so a
+                // future bypass mechanism inherits the right telemetry).
+                this.emitAllowedToolsEvents(skill);
+                // `context: fork` advisory hint. Same advisory wiring as the
+                // caller-pin path (`renderActiveSkillsBlock`), so the operator
+                // sees the same fork-declined surface regardless of how the
+                // skill was activated. SDK 2.0 has no multi-agent runtime; the
+                // body still loads inline.
+                if (skill.frontmatter.context === 'fork') {
+                    this.skills.forwardEvents([
+                        {
+                            kind: 'sdk.skill.fork_declined',
+                            skill: skill.fqn,
+                            ...(skill.frontmatter.agent !== undefined
+                                ? { agent: capAgentField(skill.frontmatter.agent) }
+                                : {}),
+                            reason: 'no_multi_agent',
+                        },
+                    ]);
+                }
+            }
+        }
+        return successTextEnvelope(texts.join('\n\n'));
+    }
+    /**
+     * Convert an activation-resolver failure into the matching telemetry
+     * event(s). Cycles + unresolved-dep failures piggyback on the existing
+     * `sdk.skill.error` channel; trust violations and cap breaches have
+     * dedicated event kinds.
+     */
+    emitResolverFailure(root, failure) {
+        switch (failure.outcome) {
+            case 'requires_trust_violation':
+                this.skills.forwardEvents([
+                    {
+                        kind: 'sdk.skill.requires_trust_denied',
+                        parent: root.fqn,
+                        child: failure.child.fqn,
+                        reason: failure.reason,
+                    },
+                ]);
+                return;
+            case 'requires_cap_exceeded':
+                this.skills.forwardEvents([
+                    {
+                        kind: 'sdk.skill.requires_cap_exceeded',
+                        parent: root.fqn,
+                        kind_breach: failure.kind,
+                        limit: failure.limit,
+                        actual: failure.actual,
+                    },
+                ]);
+                return;
+            case 'requires_cycle':
+                this.skills.forwardEvents([
+                    {
+                        kind: 'sdk.skill.error',
+                        severity: 'error',
+                        message: `requires: cycle detected at ${failure.fqn} (root ${root.fqn})`,
+                    },
+                ]);
+                return;
+            case 'requires_unresolved':
+                this.skills.forwardEvents([
+                    {
+                        kind: 'sdk.skill.error',
+                        severity: 'error',
+                        message: `requires: unresolved dependency ${failure.specifier} (root ${root.fqn})`,
+                    },
+                ]);
+                return;
+        }
+    }
+    /**
+     * Emit the `allowed-tools` telemetry shape (`applied` for trusted,
+     * `advisory` for third-party). Same logic as the SDK's caller-pin
+     * activation path; kept in sync intentionally.
+     */
+    emitAllowedToolsEvents(skill) {
+        const tools = skill.frontmatter['allowed-tools'];
+        if (tools === undefined || tools.length === 0)
+            return;
+        const tokens = tools.map((t) => (t.args !== undefined ? `${t.tool}(${t.args})` : t.tool));
+        this.skills.forwardEvents([
+            this.skills.isTrusted(skill)
+                ? { kind: 'sdk.skill.allowed_tools_applied', skill: skill.fqn, tools: tokens }
+                : { kind: 'sdk.skill.allowed_tools_advisory', skill: skill.fqn, tools: tokens },
+        ]);
+    }
+    // ---------------------------------------------------------------------
+    // get_skill_file
+    // ---------------------------------------------------------------------
+    async handleGetSkillFile(args) {
+        if (typeof args.name !== 'string' || args.name.length === 0) {
+            return errorEnvelope('get_skill_file: `name` is required and must be a non-empty string');
+        }
+        if (typeof args.path !== 'string' || args.path.length === 0) {
+            return errorEnvelope('get_skill_file: `path` is required and must be a non-empty string');
+        }
+        const skill = await this.skills.get(args.name);
+        if (skill === null) {
+            this.emitTel({
+                kind: 'sdk.skill.file_rejected',
+                skill: args.name,
+                path: args.path,
+                reason: 'not_found',
+            });
+            return errorEnvelope(`Skill '${args.name}' not found in catalog. Use list_skills to discover available skills.`);
+        }
+        let resolved;
+        try {
+            resolved = resolveSkillFilePath(skill.path, args.path);
+        }
+        catch (err) {
+            const reason = err instanceof SkillPathError ? err.reason : 'invalid_path';
+            const message = err instanceof Error ? err.message : String(err);
+            this.emitTel({
+                kind: 'sdk.skill.file_rejected',
+                skill: skill.fqnNoVersion,
+                path: args.path,
+                reason,
+            });
+            return errorEnvelope(message);
+        }
+        // Disallow reading the skill's own manifest file via this tool — the
+        // slim-index + get_skill already cover that, and exposing the
+        // manifest would let a caller bypass the trust gate on body loading.
+        //
+        // Defence in depth: reject on EITHER of two checks (so a quirk in
+        // one cannot silently bypass the gate):
+        //
+        //   1. **Basename match against the known manifest names** — the
+        //      walker accepts `SKILL.md` and `skill.md`. A user-supplied
+        //      relative path resolving to either filename at the skill
+        //      root is the manifest by construction. Match is
+        //      case-insensitive at the basename level so on case-
+        //      sensitive filesystems a request for `Skill.md` (typo / probe)
+        //      still gets rejected with a clear reason rather than ENOENT.
+        //   2. **Canonical-path equality** with the walker-recorded
+        //      `skill.skillFile` — covers symlinks that route to the
+        //      manifest via a different relative path. On case-insensitive
+        //      filesystems (macOS HFS+/APFS, Windows NTFS default) the two
+        //      canonical strings may differ in casing yet point to the same
+        //      inode; comparison is therefore also case-insensitive.
+        //
+        // (Defense against a workspace where a symlink or case-insensitive
+        // filesystem points a different relative path at the manifest.)
+        const KNOWN_MANIFEST_NAMES = ['skill.md'];
+        const relBasename = resolved.relative.includes('/')
+            ? resolved.relative.slice(resolved.relative.lastIndexOf('/') + 1)
+            : resolved.relative;
+        const relDirIsRoot = !resolved.relative.includes('/');
+        const isManifestByName = relDirIsRoot && KNOWN_MANIFEST_NAMES.includes(relBasename.toLowerCase());
+        let canonManifest;
+        try {
+            canonManifest = fsRealpathSync(skill.skillFile);
+        }
+        catch {
+            canonManifest = '\0absent';
+        }
+        const isManifestByPath = resolved.absolute === canonManifest ||
+            resolved.absolute.toLowerCase() === canonManifest.toLowerCase();
+        if (isManifestByName || isManifestByPath) {
+            this.emitTel({
+                kind: 'sdk.skill.file_rejected',
+                skill: skill.fqnNoVersion,
+                path: args.path,
+                reason: 'invalid_path',
+            });
+            return errorEnvelope("get_skill_file cannot return the skill's manifest (SKILL.md / skill.md); use get_skill to load a skill body.");
+        }
+        const cacheKey = `${skill.fqn}|${resolved.relative}`;
+        const cached = this.fileCache.get(cacheKey);
+        if (cached !== undefined) {
+            this.emitTel({
+                kind: 'sdk.skill.file_loaded',
+                skill: skill.fqnNoVersion,
+                path: resolved.relative,
+                bytes: cached.content.byteLength,
+                cached: true,
+            });
+            return this.renderFileEnvelope(skill, cached);
+        }
+        let stat;
+        try {
+            stat = await fs.stat(resolved.absolute);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.emitTel({
+                kind: 'sdk.skill.file_rejected',
+                skill: skill.fqnNoVersion,
+                path: resolved.relative,
+                reason: 'not_found',
+            });
+            return errorEnvelope(`file not found in skill '${skill.fqnNoVersion}': ${msg}`);
+        }
+        if (!stat.isFile()) {
+            this.emitTel({
+                kind: 'sdk.skill.file_rejected',
+                skill: skill.fqnNoVersion,
+                path: resolved.relative,
+                reason: 'invalid_path',
+            });
+            return errorEnvelope(`path is not a regular file in skill '${skill.fqnNoVersion}'`);
+        }
+        if (stat.size > FILE_HARD_BYTES) {
+            this.emitTel({
+                kind: 'sdk.skill.file_rejected',
+                skill: skill.fqnNoVersion,
+                path: resolved.relative,
+                reason: 'too_large',
+            });
+            return errorEnvelope(`file size exceeds ${FILE_HARD_BYTES}-byte cap; consider splitting (${stat.size} bytes).`);
+        }
+        const data = await fs.readFile(resolved.absolute);
+        // Defensive: re-check after read; a file can grow between stat + read.
+        if (data.byteLength > FILE_HARD_BYTES) {
+            this.emitTel({
+                kind: 'sdk.skill.file_rejected',
+                skill: skill.fqnNoVersion,
+                path: resolved.relative,
+                reason: 'too_large',
+            });
+            return errorEnvelope(`file grew past ${FILE_HARD_BYTES}-byte cap during read (${data.byteLength} bytes).`);
+        }
+        const { mime, isText } = detectMime(resolved.relative);
+        const cachedEntry = { content: data, mime, isText };
+        this.fileCache.set(cacheKey, cachedEntry);
+        this.emitTel({
+            kind: 'sdk.skill.file_loaded',
+            skill: skill.fqnNoVersion,
+            path: resolved.relative,
+            bytes: data.byteLength,
+            cached: false,
+        });
+        return this.renderFileEnvelope(skill, cachedEntry);
+    }
+    /**
+     * Render the file envelope, applying substitutions to markdown / text
+     * content. Cache hits go through the same path so substitutions apply
+     * even on cached reads.
+     */
+    renderFileEnvelope(skill, file) {
+        if (file.isText && file.mime === 'text/markdown') {
+            const ambient = this.resolveContext !== undefined ? this.resolveContext() : {};
+            const ctx = {
+                skill: skill.fqn,
+                named: skill.frontmatter.arguments,
+                skillDir: skill.path,
+                ...(ambient.sessionId !== undefined ? { sessionId: ambient.sessionId } : {}),
+                ...(ambient.effort !== undefined ? { effort: ambient.effort } : {}),
+            };
+            const text = file.content.toString('utf-8');
+            const substituted = substituteWithArgumentsTrailer(text, ctx);
+            this.emitSubstitutionWarnings(skill.fqn, substituted.warnings);
+            return {
+                content: [{ type: 'text', text: substituted.text }],
+                isError: false,
+            };
+        }
+        return fileResultEnvelope(file);
+    }
+    /**
+     * Forward substitution warnings from `substitute(...)` through the
+     * manager's telemetry sink. Each `SubstitutionWarning` becomes one
+     * `sdk.skill.substitution_warn` event keyed to the skill that emitted it.
+     */
+    emitSubstitutionWarnings(fqn, warnings) {
+        if (warnings.length === 0)
+            return;
+        this.skills.forwardEvents(warnings.map((w) => ({
+            kind: 'sdk.skill.substitution_warn',
+            skill: fqn,
+            reference: w.reference,
+            reason: w.reason,
+        })));
+    }
+    /**
+     * Forward MCP-specific telemetry through the manager's sink. The base
+     * `SkillEvent` union doesn't include these MCP-only kinds; the
+     * manager's sink accepts a superset, so we cast through `unknown` at
+     * the boundary. Consumers reading `SkillEvent` discriminate by `kind`
+     * literal.
+     */
+    emitTel(event) {
+        if (this.emit !== undefined) {
+            try {
+                this.emit(event);
+            }
+            catch {
+                // Telemetry sinks must never crash the MCP dispatch path.
+            }
+        }
+        // Also forward to the SkillsManager's configured sink so the
+        // consumer sees one consistent event surface for the base + MCP
+        // event kinds.
+        this.skills.forwardEvents([event]);
+    }
+}
+// ---------------------------------------------------------------------------
+// McpInProcessHandler adapter
+// ---------------------------------------------------------------------------
+/**
+ * Adapt a {@link QodoSkillsMcpServer} to the {@link McpInProcessHandler}
+ * shape expected by `client.qar.registerMcp('qodo-skills', { transport:
+ * 'sdk', handler })`. The handler unwraps the wire `{ tool_name, arguments }`
+ * shape and delegates to {@link QodoSkillsMcpServer.callTool}.
+ *
+ * The returned value is the MCP envelope `{ content, isError? }`. QAR's
+ * agent loop reads `content[0].text` (or `content[0].data` for images) as
+ * the tool call's response payload.
+ */
+export function asMcpHandler(server) {
+    return async (req) => {
+        const result = await server.callTool(req.tool_name, req.arguments);
+        return result;
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Normalize the LLM-supplied `arguments` argument into the
+ * `SubstitutionContext` shape. Accepts:
+ *
+ *   - `string[]` — already shell-parsed (the documented contract). Joined
+ *     with spaces to derive `argumentsText` for `$ARGUMENTS`.
+ *   - `string` — bare text, parsed via {@link parseArgv} for indexed access.
+ *
+ * Returns `undefined` when the argument is missing or empty so the caller
+ * can omit the field from the context (rather than render an empty
+ * `ARGUMENTS:` trailer).
+ */
+function normalizeArgumentsArg(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (Array.isArray(raw)) {
+        const argv = raw.filter((s) => typeof s === 'string');
+        if (argv.length === 0)
+            return undefined;
+        return { text: argv.join(' '), argv };
+    }
+    if (typeof raw === 'string') {
+        if (raw.length === 0)
+            return undefined;
+        // Delegate to `parseArgv` from the substitute module so the parsing
+        // rules stay in one place.
+        return { text: raw, argv: parseArgv(raw) };
+    }
+    return undefined;
+}
+function filterByQuery(skills, q) {
+    const needle = q.toLowerCase();
+    return skills.filter((skill) => {
+        if (skill.name.toLowerCase().includes(needle))
+            return true;
+        if (skill.fqnNoVersion.toLowerCase().includes(needle))
+            return true;
+        const desc = (skill.frontmatter.description ?? '').toLowerCase();
+        if (desc.includes(needle))
+            return true;
+        const when = (skill.frontmatter.when_to_use ?? '').toLowerCase();
+        if (when.includes(needle))
+            return true;
+        return false;
+    });
+}
+function toListEntry(skill) {
+    const source = {
+        type: skill.source.type,
+        ...(skill.source.type === 'project' || skill.source.type === 'user' || skill.source.type === 'config' || skill.source.type === 'bundled'
+            ? skill.source.path !== undefined
+                ? { path: skill.source.path }
+                : {}
+            : skill.source.type === 'package'
+                ? { packageName: skill.source.packageName }
+                : {}),
+    };
+    const entry = {
+        fqn: skill.fqn,
+        name: skill.name,
+        vendor: skill.vendor,
+        version: skill.version,
+        description: truncateCombined(skill.frontmatter.description, skill.frontmatter.when_to_use)
+            .description,
+        ...(skill.frontmatter.when_to_use !== undefined
+            ? {
+                when_to_use: truncateCombined(skill.frontmatter.description, skill.frontmatter.when_to_use)
+                    .when_to_use,
+            }
+            : {}),
+        tier: skill.trustTier,
+        source,
+        ...(skill.frontmatter['disable-model-invocation'] === true ? { user_invocable_only: true } : {}),
+        ...(skill.frontmatter.requires !== undefined && skill.frontmatter.requires.length > 0
+            ? { requires: skill.frontmatter.requires }
+            : {}),
+    };
+    return entry;
+}
+/** Per-entry char cap on `description + when_to_use` (mirrors slim-index entry cap). */
+const PER_ENTRY_CAP = 1536;
+function truncateCombined(desc, when) {
+    const d = desc ?? '';
+    if (when === undefined) {
+        return {
+            description: d.length <= PER_ENTRY_CAP ? d : `${d.slice(0, PER_ENTRY_CAP - 1)}…`,
+            when_to_use: undefined,
+        };
+    }
+    const combinedLen = d.length + 1 + when.length;
+    if (combinedLen <= PER_ENTRY_CAP) {
+        return { description: d, when_to_use: when };
+    }
+    // Truncate when_to_use first; description is the load-bearing prose.
+    const remaining = Math.max(0, PER_ENTRY_CAP - d.length - 2);
+    if (remaining <= 0) {
+        return {
+            description: d.slice(0, PER_ENTRY_CAP - 1) + '…',
+            when_to_use: undefined,
+        };
+    }
+    return { description: d, when_to_use: `${when.slice(0, remaining)}…` };
+}
+function detectMime(relPath) {
+    const lower = relPath.toLowerCase();
+    const dotIndex = lower.lastIndexOf('.');
+    const ext = dotIndex >= 0 ? lower.slice(dotIndex) : '';
+    if (TEXT_EXTENSIONS.has(ext)) {
+        return { mime: TEXT_EXTENSIONS.get(ext), isText: true };
+    }
+    if (IMAGE_EXTENSIONS.has(ext)) {
+        return { mime: IMAGE_EXTENSIONS.get(ext), isText: false };
+    }
+    return { mime: 'application/octet-stream', isText: false };
+}
+function successTextEnvelope(text) {
+    return {
+        content: [{ type: 'text', text }],
+        isError: false,
+    };
+}
+function successJsonEnvelope(value) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value) }],
+        isError: false,
+    };
+}
+function errorEnvelope(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+/**
+ * Map an activation-resolver failure variant onto the `invocation_denied`
+ * reason enum the MCP server emits via telemetry.
+ */
+function mapResolverFailureToDeniedReason(outcome) {
+    switch (outcome) {
+        case 'requires_trust_violation':
+            return 'requires_trust_violation';
+        case 'requires_cap_exceeded':
+            return 'requires_cap_exceeded';
+        case 'requires_cycle':
+            return 'requires_cycle';
+        case 'requires_unresolved':
+            return 'requires_unresolved';
+    }
+}
+function fileResultEnvelope(file) {
+    if (file.isText) {
+        return {
+            content: [{ type: 'text', text: file.content.toString('utf-8') }],
+            isError: false,
+        };
+    }
+    if (file.mime.startsWith('image/')) {
+        return {
+            content: [
+                {
+                    type: 'image',
+                    data: file.content.toString('base64'),
+                    mimeType: file.mime,
+                },
+            ],
+            isError: false,
+        };
+    }
+    // Non-image binary files return a descriptive text marker, not
+    // the raw base64. Pumping arbitrary base64 into the model's conversation
+    // pollutes the context without adding signal: nothing reads multi-KB
+    // base64 from a tool result usefully, and the bytes count against the
+    // window. Authors who need binary access ship a script that decodes the
+    // file out-of-band.
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `[binary file: ${file.content.byteLength} bytes, ${file.mime}. Decode externally.]`,
+            },
+        ],
+        isError: false,
+    };
+}
+//# sourceMappingURL=server.js.map