codeep 1.3.41 → 2.0.0

package/dist/utils/mcpStreamableHttp.js

@@ -0,0 +1,207 @@
+/**
+ * MCP Streamable HTTP transport — the spec successor to the original
+ * HTTP+SSE transport, used by cloud-hosted MCP servers (Anthropic remote
+ * servers, internal HTTP wrappers, etc.).
+ *
+ * Per the 2025-03 spec, a single URL endpoint accepts both:
+ *   - POST { jsonrpc, id, method, params } → JSON response, or
+ *     text/event-stream of one-or-more JSON-RPC frames.
+ *   - GET                                  → text/event-stream channel
+ *     for server-initiated notifications and requests (sampling, etc.).
+ *
+ * This client opens the GET stream lazily on the first message the server
+ * tells us to expect — many simple HTTP servers never send anything
+ * unsolicited, so we don't burn a TCP connection waiting.
+ *
+ * Session continuity uses the `mcp-session-id` header. The server sets it
+ * on the initialize response; we echo it on every subsequent request.
+ */
+/** Hard cap on a single SSE response stream. Bounds OOM risk from a
+ *  remote server that pushes unbounded data on either the POST reply or
+ *  the long-lived GET notification channel. 10 MB is comfortably above
+ *  any legitimate MCP frame (tools/list, resources/read) and well below
+ *  default Node heap limits. */
+const MAX_SSE_BYTES = 10 * 1024 * 1024;
+export class StreamableHttpClient {
+    opts;
+    sessionId = null;
+    notificationAbort = null;
+    stopped = false;
+    /** True after the server has set a session id (i.e. it tracks state). */
+    get hasServerSession() {
+        return this.sessionId !== null;
+    }
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Issue a JSON-RPC frame as POST. Reply may be a single JSON response
+     * (synchronous tools/call), or an SSE stream of one-or-more responses
+     * + notifications. The transport invokes `onFrame` for every message
+     * it sees on the response, regardless of shape.
+     */
+    async send(frame) {
+        if (this.stopped)
+            throw new Error('StreamableHttpClient.stop() already called');
+        const headers = {
+            'Content-Type': 'application/json',
+            // Accept both shapes so the server can pick. Spec requires both.
+            'Accept': 'application/json, text/event-stream',
+            ...this.opts.headers,
+        };
+        if (this.sessionId)
+            headers['mcp-session-id'] = this.sessionId;
+        const res = await fetch(this.opts.url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(frame),
+        });
+        // 202 Accepted = fire-and-forget (notifications); nothing to parse.
+        if (res.status === 202)
+            return;
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`MCP HTTP ${res.status} ${res.statusText}: ${text.slice(0, 300)}`);
+        }
+        // Server may set the session id on the first response. Capture and
+        // open the notification stream if it did (the server now has state
+        // and may want to push us notifications/requests).
+        const newSession = res.headers.get('mcp-session-id');
+        if (newSession && newSession !== this.sessionId) {
+            this.sessionId = newSession;
+            // Don't await — we want POST to return as soon as the response is
+            // parsed; the notification stream lives independently.
+            void this.openNotificationStream();
+        }
+        const contentType = res.headers.get('content-type') ?? '';
+        if (contentType.includes('text/event-stream')) {
+            // Process inline streaming response (multiple frames possible).
+            await this.consumeSseBody(res);
+        }
+        else {
+            // Single JSON response.
+            const body = await res.json().catch(() => null);
+            if (body && typeof body === 'object') {
+                this.opts.onFrame(body);
+            }
+        }
+    }
+    /**
+     * Open the server-push SSE channel. Idempotent — won't open twice if
+     * already streaming. Errors are surfaced via `onError`, not thrown, so
+     * a transient network blip doesn't crash the agent loop.
+     */
+    async openNotificationStream() {
+        if (this.notificationAbort || this.stopped)
+            return;
+        this.notificationAbort = new AbortController();
+        const headers = {
+            'Accept': 'text/event-stream',
+            ...this.opts.headers,
+        };
+        if (this.sessionId)
+            headers['mcp-session-id'] = this.sessionId;
+        try {
+            const res = await fetch(this.opts.url, {
+                method: 'GET',
+                headers,
+                signal: this.notificationAbort.signal,
+            });
+            if (!res.ok || !res.body) {
+                // Some servers don't support the GET channel — that's fine, they
+                // just won't push anything. Don't escalate to an error.
+                return;
+            }
+            await this.consumeSseBody(res);
+        }
+        catch (err) {
+            if (err.name === 'AbortError')
+                return;
+            this.opts.onError?.(err);
+        }
+        finally {
+            this.notificationAbort = null;
+        }
+    }
+    /**
+     * Parse a `text/event-stream` body, invoking `onFrame` for each JSON
+     * payload. SSE framing is intentionally permissive — we treat any line
+     * starting with `data:` as one event's payload and join multi-line
+     * data: blocks until a blank line.
+     *
+     * Bounded by `MAX_SSE_BYTES`: a misbehaving or malicious remote server
+     * can push unbounded data on an SSE channel — without a cap, the
+     * accumulating buffer would OOM the agent. We track cumulative bytes
+     * read and bail with `onError` past the cap.
+     */
+    async consumeSseBody(res) {
+        if (!res.body)
+            return;
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        let buffer = '';
+        let bytesRead = 0;
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                bytesRead += value.byteLength;
+                if (bytesRead > MAX_SSE_BYTES) {
+                    // Abort the reader so we don't keep allocating; surface via
+                    // onError so the registry can mark the server as failed.
+                    try {
+                        await reader.cancel();
+                    }
+                    catch { /* best-effort */ }
+                    this.opts.onError?.(new Error(`mcp http: SSE body exceeded ${MAX_SSE_BYTES} bytes; aborting (likely a misbehaving server)`));
+                    return;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                // Split on the SSE event boundary (two consecutive newlines).
+                // CRLF and LF both legal — normalise first.
+                buffer = buffer.replace(/\r\n/g, '\n');
+                let boundary = buffer.indexOf('\n\n');
+                while (boundary >= 0) {
+                    const eventBlock = buffer.slice(0, boundary);
+                    buffer = buffer.slice(boundary + 2);
+                    this.dispatchSseEvent(eventBlock);
+                    boundary = buffer.indexOf('\n\n');
+                }
+            }
+        }
+        catch (err) {
+            if (err.name === 'AbortError')
+                return;
+            throw err;
+        }
+    }
+    dispatchSseEvent(block) {
+        // Each event is a set of `field:value` lines. We only care about the
+        // `data:` field — `event:` types are server-defined; the MCP spec
+        // doesn't use them for transport framing.
+        const dataLines = [];
+        for (const line of block.split('\n')) {
+            if (line.startsWith('data:'))
+                dataLines.push(line.slice(5).trimStart());
+        }
+        if (dataLines.length === 0)
+            return;
+        const raw = dataLines.join('\n');
+        try {
+            const msg = JSON.parse(raw);
+            this.opts.onFrame(msg);
+        }
+        catch {
+            // Malformed JSON in the stream — skip rather than blow up.
+        }
+    }
+    /** Tear down the notification stream and refuse further sends. */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.notificationAbort?.abort();
+        this.notificationAbort = null;
+    }
+}

package/dist/utils/openrouterPrefs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenRouter provider-routing preferences.
+ *
+ * OpenRouter lets the caller bias which upstream provider its router
+ * picks for a given model — useful for cost, latency, geography, or
+ * privacy reasons. The shape we send in the request body's `provider`
+ * field follows the OpenRouter spec
+ * (https://openrouter.ai/docs#provider-routing):
+ *
+ *   {
+ *     "order":          ["DeepInfra", "Together"],   // try first in order
+ *     "allow_fallbacks": true,                        // fall back to others if order fails
+ *     "ignore":         ["OpenAI"],                   // never use these
+ *     "data_collection": "deny" | "allow",            // privacy gate
+ *     "require_parameters": true,                     // strict spec compliance
+ *   }
+ *
+ * We store the user's preferences in `conf` so they persist across CLI
+ * launches. Empty / unset means "let OpenRouter route freely".
+ */
+export interface OpenRouterPreferences {
+    order?: string[];
+    allow_fallbacks?: boolean;
+    ignore?: string[];
+    data_collection?: 'allow' | 'deny';
+    require_parameters?: boolean;
+}
+/**
+ * Return the user's stored preferences, or null if none set. Returning
+ * null (vs empty object) lets `agentChat` omit the `provider` field
+ * entirely — OpenRouter is happier with no field than with an empty one.
+ */
+export declare function readOpenRouterPreferences(): OpenRouterPreferences | null;
+export declare function writeOpenRouterPreferences(prefs: OpenRouterPreferences | null): void;
+/** Render preferences for `/openrouter` command output. */
+export declare function formatOpenRouterPreferences(prefs: OpenRouterPreferences | null): string;

package/dist/utils/openrouterPrefs.js

@@ -0,0 +1,83 @@
+/**
+ * OpenRouter provider-routing preferences.
+ *
+ * OpenRouter lets the caller bias which upstream provider its router
+ * picks for a given model — useful for cost, latency, geography, or
+ * privacy reasons. The shape we send in the request body's `provider`
+ * field follows the OpenRouter spec
+ * (https://openrouter.ai/docs#provider-routing):
+ *
+ *   {
+ *     "order":          ["DeepInfra", "Together"],   // try first in order
+ *     "allow_fallbacks": true,                        // fall back to others if order fails
+ *     "ignore":         ["OpenAI"],                   // never use these
+ *     "data_collection": "deny" | "allow",            // privacy gate
+ *     "require_parameters": true,                     // strict spec compliance
+ *   }
+ *
+ * We store the user's preferences in `conf` so they persist across CLI
+ * launches. Empty / unset means "let OpenRouter route freely".
+ */
+import { config } from '../config/index.js';
+/**
+ * Return the user's stored preferences, or null if none set. Returning
+ * null (vs empty object) lets `agentChat` omit the `provider` field
+ * entirely — OpenRouter is happier with no field than with an empty one.
+ */
+export function readOpenRouterPreferences() {
+    const raw = config.get('openrouterPreferences');
+    if (!raw || typeof raw !== 'object')
+        return null;
+    // Strip empty arrays — those would tell OpenRouter "use exactly nothing".
+    const cleaned = {};
+    if (Array.isArray(raw.order) && raw.order.length > 0)
+        cleaned.order = raw.order;
+    if (Array.isArray(raw.ignore) && raw.ignore.length > 0)
+        cleaned.ignore = raw.ignore;
+    if (typeof raw.allow_fallbacks === 'boolean')
+        cleaned.allow_fallbacks = raw.allow_fallbacks;
+    if (raw.data_collection === 'allow' || raw.data_collection === 'deny')
+        cleaned.data_collection = raw.data_collection;
+    if (typeof raw.require_parameters === 'boolean')
+        cleaned.require_parameters = raw.require_parameters;
+    return Object.keys(cleaned).length > 0 ? cleaned : null;
+}
+export function writeOpenRouterPreferences(prefs) {
+    if (!prefs) {
+        // conf's typing wants a value of the right shape; `undefined` is a
+        // valid clearing signal but doesn't match TS' strict optional.
+        config.set('openrouterPreferences', undefined);
+        return;
+    }
+    config.set('openrouterPreferences', prefs);
+}
+/** Render preferences for `/openrouter` command output. */
+export function formatOpenRouterPreferences(prefs) {
+    if (!prefs) {
+        return [
+            '## OpenRouter preferences',
+            '',
+            '_No routing preferences set — OpenRouter picks freely._',
+            '',
+            'Tune routing with:',
+            '- `/openrouter prefer <provider1>,<provider2>` — try these providers first (in order)',
+            '- `/openrouter ignore <provider1>,<provider2>` — never route through these',
+            '- `/openrouter fallbacks on|off` — allow fallback when preferred providers fail',
+            '- `/openrouter privacy strict|allow` — strict = `data_collection: deny`',
+            '- `/openrouter clear` — drop all preferences',
+        ].join('\n');
+    }
+    const lines = ['## OpenRouter preferences', ''];
+    if (prefs.order)
+        lines.push(`- **Prefer**: ${prefs.order.map(p => `\`${p}\``).join(', ')}`);
+    if (prefs.ignore)
+        lines.push(`- **Ignore**: ${prefs.ignore.map(p => `\`${p}\``).join(', ')}`);
+    if (typeof prefs.allow_fallbacks === 'boolean')
+        lines.push(`- **Fallbacks**: ${prefs.allow_fallbacks ? 'allowed' : 'disabled'}`);
+    if (prefs.data_collection)
+        lines.push(`- **Data collection**: ${prefs.data_collection}`);
+    if (prefs.require_parameters)
+        lines.push(`- **Require parameters**: strict`);
+    lines.push('', 'Clear with `/openrouter clear`.');
+    return lines.join('\n');
+}

package/dist/utils/skillBundles.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Structured skill bundles — Codeep's answer to Claude Code-style skills.
+ *
+ * Unlike the JSON-manifest "skills" in `skills.ts` (which are sequential
+ * step lists triggered by the user via `/<name>`), bundles are
+ * agent-discovered capabilities the model picks up on its own. Each
+ * bundle lives in a directory:
+ *
+ *   <workspace>/.codeep/skills/<name>/SKILL.md   (project-scoped)
+ *   ~/.codeep/skills/<name>/SKILL.md             (global)
+ *
+ * Project bundles shadow global ones with the same name. The bundle dir
+ * may also contain auxiliary files (`assets/`, `scripts/`, …) that the
+ * SKILL.md body refers to — we don't enforce any sub-structure.
+ *
+ * The SKILL.md format is a deliberate superset of Claude Code's skills
+ * format so existing skills can be dropped in unchanged. Frontmatter
+ * keys we recognise:
+ *
+ *   name:               (required) short slug; matches dir name by default
+ *   description:        (required) one-sentence summary for the catalog
+ *   allowed-tools:      (optional) array of tool names this skill may call
+ *   triggers:           (optional) array of phrases that hint when to use
+ *   version:            (optional) semver string
+ *   author:             (optional) free text
+ *
+ * Codeep-specific extensions (skipped by Claude Code parsers, valid YAML):
+ *
+ *   codeep-min-version: (optional) require Codeep CLI ≥ this version
+ *   codeep-requires-mcp: (optional) array of MCP server names that must
+ *                        be registered for this skill to run
+ *
+ * The body of SKILL.md is freeform Markdown — instructions the agent
+ * reads when it decides to invoke the skill.
+ */
+export interface SkillBundleMeta {
+    /** Slug — defaults to the directory name if frontmatter `name` is missing. */
+    name: string;
+    /** One-line summary shown in the catalog. */
+    description: string;
+    /** Filesystem path of the bundle directory. */
+    source: string;
+    /** 'project' if loaded from `<workspace>/.codeep/skills`, else 'global'. */
+    scope: 'project' | 'global';
+    /** Subset of tools the skill is allowed to call (advisory in v2.0; enforced in 2.1+). */
+    allowedTools: string[];
+    /** Hint phrases that suggest when to use this skill (sysprompt-only signal). */
+    triggers: string[];
+    /** Optional semver string. */
+    version?: string;
+    /** Optional author free text. */
+    author?: string;
+    /** Optional minimum Codeep version (semver string). */
+    codeepMinVersion?: string;
+    /** Optional list of MCP servers the skill needs registered. */
+    requiresMcp: string[];
+    /** Raw frontmatter — kept for `/skills detail <name>` introspection. */
+    frontmatterRaw: Record<string, unknown>;
+}
+export interface SkillBundle extends SkillBundleMeta {
+    /** Body content (everything after the frontmatter). */
+    body: string;
+}
+/**
+ * Load all skill bundles available in this workspace. Project entries
+ * shadow global entries with the same name.
+ */
+export declare function loadSkillBundles(workspaceRoot?: string): SkillBundle[];
+/** Find a single bundle by name (case-insensitive). */
+export declare function findSkillBundle(name: string, workspaceRoot?: string): SkillBundle | null;
+/**
+ * Build a compact catalog block for the agent's system prompt. Each entry
+ * is `name — description (triggers)` so the model can pattern-match user
+ * intent to a skill name. Capped so a workspace with hundreds of skills
+ * can't blow the token budget.
+ */
+export declare function formatBundlesForSysprompt(bundles: SkillBundle[]): string;
+/** Render a bundle list as a Markdown block for `/skills bundles`. */
+export declare function formatBundleList(bundles: SkillBundle[]): string;
+/**
+ * One-line summary for the welcome banner — same informed-consent
+ * pattern as custom commands and hooks. Empty string if no bundles.
+ */
+export declare function summarizeBundles(workspaceRoot: string): string;

package/dist/utils/skillBundles.js

@@ -0,0 +1,257 @@
+/**
+ * Structured skill bundles — Codeep's answer to Claude Code-style skills.
+ *
+ * Unlike the JSON-manifest "skills" in `skills.ts` (which are sequential
+ * step lists triggered by the user via `/<name>`), bundles are
+ * agent-discovered capabilities the model picks up on its own. Each
+ * bundle lives in a directory:
+ *
+ *   <workspace>/.codeep/skills/<name>/SKILL.md   (project-scoped)
+ *   ~/.codeep/skills/<name>/SKILL.md             (global)
+ *
+ * Project bundles shadow global ones with the same name. The bundle dir
+ * may also contain auxiliary files (`assets/`, `scripts/`, …) that the
+ * SKILL.md body refers to — we don't enforce any sub-structure.
+ *
+ * The SKILL.md format is a deliberate superset of Claude Code's skills
+ * format so existing skills can be dropped in unchanged. Frontmatter
+ * keys we recognise:
+ *
+ *   name:               (required) short slug; matches dir name by default
+ *   description:        (required) one-sentence summary for the catalog
+ *   allowed-tools:      (optional) array of tool names this skill may call
+ *   triggers:           (optional) array of phrases that hint when to use
+ *   version:            (optional) semver string
+ *   author:             (optional) free text
+ *
+ * Codeep-specific extensions (skipped by Claude Code parsers, valid YAML):
+ *
+ *   codeep-min-version: (optional) require Codeep CLI ≥ this version
+ *   codeep-requires-mcp: (optional) array of MCP server names that must
+ *                        be registered for this skill to run
+ *
+ * The body of SKILL.md is freeform Markdown — instructions the agent
+ * reads when it decides to invoke the skill.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/**
+ * Tolerant YAML-frontmatter parser — handles `key: value`, `key: [a, b]`,
+ * and `key:` followed by `- item` block-list lines. Quoted strings are
+ * unquoted. We don't ship a real YAML dep for this — the keys we care
+ * about are scalars or simple arrays.
+ */
+function parseFrontmatter(raw) {
+    // BOM + CRLF normalisation. Real-world files copy/paste from various
+    // editors and pick up either; YAML strictly forbids tabs in scalars
+    // but we don't care for the keys we read.
+    const normalised = raw.replace(/^/, '').replace(/\r\n/g, '\n');
+    const match = normalised.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return { meta: {}, body: normalised };
+    const meta = {};
+    const lines = match[1].split('\n');
+    let currentKey = null;
+    let currentList = null;
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/\s+$/, '');
+        if (!line.trim()) {
+            currentKey = null;
+            currentList = null;
+            continue;
+        }
+        // Block-list item: `  - foo`
+        const listItem = line.match(/^\s+-\s+(.*)$/);
+        if (listItem && currentList) {
+            currentList.push(stripQuotes(listItem[1]));
+            continue;
+        }
+        // `key: value` or `key:` (open list)
+        const kv = line.match(/^([a-zA-Z_][\w-]*)\s*:\s*(.*?)\s*$/);
+        if (!kv)
+            continue;
+        const key = kv[1];
+        let value = kv[2];
+        if (value === '') {
+            // Empty → expecting a block list below
+            currentKey = key;
+            currentList = [];
+            meta[key] = currentList;
+            continue;
+        }
+        // Inline list: `[a, b, c]`
+        const inline = value.match(/^\[(.*)\]$/);
+        if (inline) {
+            value = inline[1].split(',').map(s => stripQuotes(s.trim())).filter(Boolean);
+        }
+        else {
+            value = stripQuotes(value);
+        }
+        meta[key] = value;
+        currentKey = null;
+        currentList = null;
+    }
+    return { meta, body: match[2].trimStart() };
+}
+function stripQuotes(s) {
+    return s.replace(/^["']|["']$/g, '');
+}
+function loadFromDir(dir, scope) {
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const bundles = [];
+    for (const entry of entries) {
+        const bundleDir = join(dir, entry);
+        let stat;
+        try {
+            stat = statSync(bundleDir);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const skillFile = join(bundleDir, 'SKILL.md');
+        if (!existsSync(skillFile))
+            continue;
+        let raw;
+        try {
+            raw = readFileSync(skillFile, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        // Cap at 256 KB — any bigger and the user is shipping something
+        // that doesn't belong in a SKILL.md. Skip silently to avoid OOM
+        // surprises when an agent run loads dozens of bundles.
+        if (raw.length > 256 * 1024)
+            continue;
+        const { meta, body } = parseFrontmatter(raw);
+        const name = typeof meta.name === 'string' && meta.name ? meta.name : entry;
+        if (!/^[a-z0-9][a-z0-9-]*$/i.test(name))
+            continue; // sanitise
+        const description = typeof meta.description === 'string' ? meta.description : '';
+        if (!description)
+            continue; // catalog entry without a description is noise
+        bundles.push({
+            name: name.toLowerCase(),
+            description,
+            source: bundleDir,
+            scope,
+            allowedTools: asStringArray(meta['allowed-tools']) ?? [],
+            triggers: asStringArray(meta.triggers) ?? [],
+            version: typeof meta.version === 'string' ? meta.version : undefined,
+            author: typeof meta.author === 'string' ? meta.author : undefined,
+            codeepMinVersion: typeof meta['codeep-min-version'] === 'string' ? meta['codeep-min-version'] : undefined,
+            requiresMcp: asStringArray(meta['codeep-requires-mcp']) ?? [],
+            frontmatterRaw: meta,
+            body,
+        });
+    }
+    return bundles;
+}
+function asStringArray(v) {
+    if (Array.isArray(v))
+        return v.filter(x => typeof x === 'string');
+    if (typeof v === 'string')
+        return [v];
+    return null;
+}
+/**
+ * Load all skill bundles available in this workspace. Project entries
+ * shadow global entries with the same name.
+ */
+export function loadSkillBundles(workspaceRoot) {
+    const global = loadFromDir(join(homedir(), '.codeep', 'skills'), 'global');
+    const project = workspaceRoot
+        ? loadFromDir(join(workspaceRoot, '.codeep', 'skills'), 'project')
+        : [];
+    const byName = new Map();
+    for (const b of global)
+        byName.set(b.name, b);
+    for (const b of project)
+        byName.set(b.name, b); // project wins
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Find a single bundle by name (case-insensitive). */
+export function findSkillBundle(name, workspaceRoot) {
+    const lower = name.toLowerCase();
+    return loadSkillBundles(workspaceRoot).find(b => b.name === lower) ?? null;
+}
+/**
+ * Build a compact catalog block for the agent's system prompt. Each entry
+ * is `name — description (triggers)` so the model can pattern-match user
+ * intent to a skill name. Capped so a workspace with hundreds of skills
+ * can't blow the token budget.
+ */
+export function formatBundlesForSysprompt(bundles) {
+    if (bundles.length === 0)
+        return '';
+    const CAP_PER_LINE = 200;
+    const CAP_TOTAL = 4000;
+    const lines = [
+        '## Available skill bundles',
+        '',
+        'You can invoke any of these by calling the `invoke_skill` tool with `{"name": "<skill_name>"}`. The tool returns the skill\'s SKILL.md content — follow its instructions step by step. Each skill is a curated workflow the user has installed; prefer it over ad-hoc steps when the user\'s request matches a skill\'s purpose.',
+        '',
+    ];
+    let used = lines.join('\n').length;
+    let skipped = 0;
+    for (const b of bundles) {
+        const triggerHint = b.triggers.length > 0 ? ` _(triggers: ${b.triggers.slice(0, 3).join(', ')})_` : '';
+        const line = `- **${b.name}** — ${b.description}${triggerHint}`;
+        const truncated = line.length > CAP_PER_LINE ? line.slice(0, CAP_PER_LINE) + '…' : line;
+        if (used + truncated.length + 1 > CAP_TOTAL) {
+            skipped++;
+            continue;
+        }
+        lines.push(truncated);
+        used += truncated.length + 1;
+    }
+    if (skipped > 0)
+        lines.push(`_(${skipped} more skills omitted to stay under the catalog budget — use \`/skills bundles\` to see all.)_`);
+    return lines.join('\n');
+}
+/** Render a bundle list as a Markdown block for `/skills bundles`. */
+export function formatBundleList(bundles) {
+    if (bundles.length === 0) {
+        return [
+            '_No skill bundles installed yet._',
+            '',
+            'Create one with `/skills create-bundle <name>` (project) or drop a directory into `~/.codeep/skills/<name>/` (global). Each needs a `SKILL.md` with at least `name` and `description` in the frontmatter.',
+        ].join('\n');
+    }
+    const project = bundles.filter(b => b.scope === 'project');
+    const global = bundles.filter(b => b.scope === 'global');
+    const lines = ['## Skill bundles', ''];
+    if (project.length) {
+        lines.push('**Project**');
+        for (const b of project)
+            lines.push(`- **${b.name}** ${b.version ? `\`v${b.version}\` ` : ''}— ${b.description}`);
+        lines.push('');
+    }
+    if (global.length) {
+        lines.push('**Global**');
+        for (const b of global)
+            lines.push(`- **${b.name}** ${b.version ? `\`v${b.version}\` ` : ''}— ${b.description}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * One-line summary for the welcome banner — same informed-consent
+ * pattern as custom commands and hooks. Empty string if no bundles.
+ */
+export function summarizeBundles(workspaceRoot) {
+    const project = loadSkillBundles(workspaceRoot).filter(b => b.scope === 'project');
+    if (project.length === 0)
+        return '';
+    return `${project.length} project skill${project.length === 1 ? '' : 's'}`;
+}