drafted 1.10.1 → 1.11.0

package/mcp/server.mjs

@@ -832,6 +832,34 @@ function summarizeSkillForSearch(skill) {
   };
 }
 
+// Ultra-lean catalog entry for browsing large libraries within an agent's token
+// budget: just enough to recognize a skill and load it by slug. Full
+// description/triggerPatterns are only needed on load.
+function compactSkillEntry(skill) {
+  if (!skill || typeof skill !== 'object') return skill;
+  return { slug: skill.slug, name: skill.name, tags: skill.tags || [] };
+}
+
+// Shape a {skills:[...]} catalog result (search or list) with limit/offset
+// pagination and an optional compact mode, so an 82-entry global catalog stays
+// within an agent's token budget. Mirrors how `search` already caps client-side.
+function shapeSkillCatalog(result, { limit, offset = 0, compact = false } = {}) {
+  if (!Array.isArray(result?.skills)) return result;
+  const total = result.skills.length;
+  const start = Math.max(0, Math.floor(Number(offset) || 0));
+  const cap = Math.min(Math.max(1, Math.floor(Number(limit) || 25)), 100);
+  const page = result.skills.slice(start, start + cap);
+  result.totalAvailable = total;
+  result.offset = start;
+  result.returned = page.length;
+  result.truncated = start + page.length < total;
+  result.skills = page.map(compact ? compactSkillEntry : summarizeSkillForSearch);
+  result.note = compact
+    ? 'Compact catalog: {slug,name,tags} only. Load full content with skill(action="load", skill="<slug>"). Pass compact=false for descriptions/triggerPatterns; use offset to page.'
+    : 'Search/list returns skill summaries only (no SKILL.md body). Use skill(action="load", skill="<slug-or-id>") for full content. Pass compact=true for a leaner {slug,name,tags} catalog; use limit/offset to page.';
+  return result;
+}
+
 // Build the structuredContent shape that the frame-preview widget reads.
 // Tools that produce or return a frame (read/write/edit) call this so the
 // model and widget see the same metadata view.
@@ -2651,9 +2679,9 @@ function collectSkillTreeForPush(dir) {
   return out;
 }
 
-tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/guidelines agents can load and follow. Dispatch by `action`: search/load/list for discovery; add/update/remove for org skills; fork/push for source-only skills; attach/detach for project binding; favorite/unfavorite for personal pins; read_file/update_file for supporting files inside a skill directory.', {
+tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/guidelines agents can load and follow. Dispatch by `action`: search/load/list for discovery; history for a skill\'s version git-log; add/update/remove for org skills; fork/push for source-only skills; attach/detach for project binding; favorite/unfavorite for personal pins; read_file/update_file for supporting files inside a skill directory.', {
   action: z.enum([
-    'search', 'load', 'list',
+    'search', 'load', 'list', 'history',
     'add', 'update', 'remove',
     'fork', 'push',
     'attach', 'detach',
@@ -2663,8 +2691,11 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
   query: z.string().optional().describe('[search] term to match against name/description/content'),
   tags: z.array(z.string()).optional().describe('[search] filter by tags; [add|update] tag list'),
   scope: z.enum(['all', 'org', 'global']).optional().describe('[search|list] library scope (default: all for search; when provided to list, lists the library instead of project/org attachments)'),
-  limit: z.number().optional().describe('[search] max results (default 25, max 100)'),
-  skill: z.string().optional().describe('[load] skill ID (UUID) or slug'),
+  limit: z.number().optional().describe('[search|list] max results per page (default 25, max 100)'),
+  offset: z.number().optional().describe('[search|list] skip N results for pagination (default 0). Response reports totalAvailable/returned/truncated.'),
+  compact: z.boolean().optional().describe('[search|list] return only {slug,name,tags} per skill instead of full summaries — for browsing large catalogs within token budget'),
+  skill: z.string().optional().describe('[load|history] skill ID (UUID) or slug'),
+  version: z.number().optional().describe('[history] fetch this version number\'s full snapshot (content included); omit for the reverse-chron version list'),
   skillId: z.string().optional().describe('[update|remove|attach|detach|favorite|unfavorite|read_file|update_file] skill ID'),
   projectId: z.string().optional().describe('[list] project to list skills for (defaults to active project; falls back to org-attached skills if no project)'),
   name: z.string().optional().describe('[add|update] skill name'),
@@ -2682,7 +2713,7 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
     const { action } = args;
     switch (action) {
       case 'search': {
-        const { query, tags, scope = 'all', limit = 25 } = args;
+        const { query, tags, scope = 'all', limit, offset, compact } = args;
         const params = new URLSearchParams();
         if (query) params.set('q', query);
         if (tags?.length) params.set('tags', tags.join(','));
@@ -2691,17 +2722,7 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         const endpoint = query ? '/api/skills/search' : '/api/skills';
         const result = await api('GET', `${endpoint}${qs ? '?' + qs : ''}`);
         markSearched(getSessionState().gates, 'skill');
-        const cap = Math.min(Math.max(1, limit || 25), 100);
-        if (Array.isArray(result?.skills)) {
-          if (result.skills.length > cap) {
-            result.totalAvailable = result.skills.length;
-            result.truncated = true;
-            result.skills = result.skills.slice(0, cap);
-          }
-          result.skills = result.skills.map(summarizeSkillForSearch);
-          result.note = 'Search/list returns skill summaries only. Use skill(action="load", skill="<slug-or-id>") to read full SKILL.md content and supporting file list.';
-        }
-        return ok(result);
+        return ok(shapeSkillCatalog(result, { limit, offset, compact }));
       }
       case 'load': {
         const { skill } = args;
@@ -2712,17 +2733,24 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         if (result?.id) getSessionState().loadedSkillIds.add(result.id);
         return ok(result);
       }
+      case 'history': {
+        // Skill version git-log. Omit `version` for the list; pass it for a
+        // single version's full snapshot (content for view/diff).
+        const { skillId, skill: slugArg, version, org } = args;
+        const extra = org ? { 'X-Drafted-Org': org } : {};
+        let id = skillId;
+        if (!id && slugArg) { const s = await api('GET', `/api/skills/slug/${slugArg}`, undefined, extra); id = s.id; }
+        if (!id) throw new Error('skillId or skill (slug) required for action=history');
+        if (version != null) return ok(await api('GET', `/api/skills/${id}/versions/${version}`, undefined, extra));
+        return ok(await api('GET', `/api/skills/${id}/versions`, undefined, extra));
+      }
       case 'list': {
         if (args.scope || args.tags?.length) {
           const params = new URLSearchParams();
           params.set('scope', args.scope || 'all');
           if (args.tags?.length) params.set('tags', args.tags.join(','));
           const result = await api('GET', `/api/skills?${params.toString()}`);
-          if (Array.isArray(result?.skills)) {
-            result.skills = result.skills.map(summarizeSkillForSearch);
-            result.note = 'Library list returns skill summaries only. Use skill(action="load", skill="<slug-or-id>") to read full SKILL.md content and supporting file list.';
-          }
-          return ok(result);
+          return ok(shapeSkillCatalog(result, { limit: args.limit, offset: args.offset, compact: args.compact }));
         }
 
         // Prefer the explicit projectId param; otherwise the active project;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "files": [