@skilder-ai/runtime 0.8.4 → 0.8.5

package/dist/index.js

@@ -144653,16 +144653,13 @@ SkillContentService = __decorate12([
 ], SkillContentService);
 
 // src/services/static-tools/init-skilder.handler.ts
-function isHatPreloaded(hatId, ctx) {
-  return ctx.identity.preloadedHatIds?.includes(hatId) ?? false;
-}
 function buildInitSkilderResponse(ctx) {
   const catalog = ctx.catalog;
-  if (!catalog || catalog.hats.length === 0 && catalog.skills.length === 0) {
+  if (!catalog || catalog.hats.length === 0) {
     return [
       "# Welcome to Skilder",
       "",
-      "No skills or hats are configured for this session.",
+      "No hats are configured for this session.",
       "",
       "Skilder provides specialized skills and tools to help you accomplish tasks."
     ].join("\n");
@@ -144670,107 +144667,35 @@ function buildInitSkilderResponse(ctx) {
   const lines = [];
   lines.push("# Welcome to Skilder");
   lines.push("");
-  lines.push("Skilder provides specialized skills and resources. Use `learn` to access resources by path.");
+  lines.push("Skilder provides specialized skills and resources. Hats are the entry point \u2014 learn a hat first, then learn individual skills to unlock their tools.");
   lines.push("");
-  lines.push("**Path Examples:**");
-  lines.push('- `learn --path "/Skill Name"` - Learn a skill and unlock its tools');
-  lines.push('- `learn --path "/Skill Name/doc.md"` - Get a resource');
-  lines.push('- `learn --path "/hats/Hat Name"` - Learn all skills in a hat');
-  lines.push('- `execute_script --path "/Skill Name/script.py --args"` - Run a script');
+  lines.push("## Available Hats");
   lines.push("");
-  const preloadedHats = catalog.hats.filter((h2) => isHatPreloaded(h2.id, ctx));
-  const discoverableHats = catalog.hats.filter((h2) => !isHatPreloaded(h2.id, ctx));
-  const preloadedSkillIds = new Set(ctx.identity.preloadedSkillIds ?? []);
-  if (discoverableHats.length > 0) {
-    lines.push("## Available Hats");
-    lines.push("");
-    lines.push('Use `learn --path "/hats/Hat Name"` to unlock all skills in a hat.');
-    lines.push("");
-    for (const hat of discoverableHats) {
-      const skillCount = hat.skillIds.length;
-      lines.push(
-        `- **${hat.name}**${hat.description ? `: ${hat.description}` : ""} (${skillCount} skill${skillCount !== 1 ? "s" : ""})`
-      );
-    }
-    lines.push("");
-  }
-  const discoverableSkills = catalog.skills.filter((s) => !preloadedSkillIds.has(s.id));
-  if (discoverableSkills.length > 0) {
-    lines.push("## Available Skills");
-    lines.push("");
-    lines.push('Use `learn --path "/Skill Name"` to unlock tools and view instructions.');
-    lines.push("");
-    for (const skill of discoverableSkills) {
-      const extras = [];
-      const learnableCount = skill.related.filter((r2) => r2.class === "learnable").length;
-      const executableCount = skill.related.filter((r2) => r2.class === "executable").length;
-      if (learnableCount > 0) {
-        extras.push(`${learnableCount} ref${learnableCount !== 1 ? "s" : ""}`);
-      }
-      if (executableCount > 0) {
-        extras.push(`${executableCount} script${executableCount !== 1 ? "s" : ""}`);
-      }
-      const extrasStr = extras.length > 0 ? ` [${extras.join(", ")}]` : "";
-      lines.push(`- **${skill.name}**${skill.description ? `: ${skill.description}` : ""}${extrasStr}`);
+  lines.push("You MUST learn a hat before doing anything else. Hats are the only entry point.");
+  lines.push("");
+  for (const hat of catalog.hats) {
+    lines.push(`### ${hat.name}`);
+    if (hat.description) {
+      lines.push(hat.description);
     }
     lines.push("");
-  }
-  if (preloadedHats.length > 0) {
-    lines.push("## Pre-loaded Hats (Ready to Use)");
-    lines.push("");
-    for (const hat of preloadedHats) {
-      lines.push(`### ${hat.name}`);
-      if (hat.description) {
-        lines.push(hat.description);
-      }
-      if (hat.instructions) {
-        lines.push("");
-        lines.push("**Instructions:**");
-        lines.push(hat.instructions);
-      }
-      lines.push("");
-      lines.push("**Skills in this hat:**");
-      for (const skillId of hat.skillIds) {
-        const skill = catalog.skills.find((s) => s.id === skillId);
-        if (skill) {
-          lines.push(`- **${skill.name}**${skill.description ? `: ${skill.description}` : ""}`);
-          if (skill.instructions) {
-            lines.push(`  - Instructions: ${skill.instructions}`);
-          }
-          if (skill.toolNames.length > 0) {
-            lines.push(`  - Tools: ${skill.toolNames.join(", ")}`);
-          }
-        }
-      }
-      lines.push("");
-    }
-  }
-  const preloadedSkills = catalog.skills.filter((s) => preloadedSkillIds.has(s.id));
-  const preloadedHatSkillIds = new Set(preloadedHats.flatMap((h2) => h2.skillIds));
-  const orphanPreloadedSkills = preloadedSkills.filter((s) => !preloadedHatSkillIds.has(s.id));
-  if (orphanPreloadedSkills.length > 0) {
-    lines.push("## Pre-loaded Skills (Ready to Use)");
+    lines.push(`**Learn this hat:** \`learn --path "/hats/${hat.name}"\``);
     lines.push("");
-    for (const skill of orphanPreloadedSkills) {
-      lines.push(`### ${skill.name}`);
-      if (skill.description) {
-        lines.push(skill.description);
-      }
-      if (skill.instructions) {
-        lines.push("");
-        lines.push("**Instructions:**");
-        lines.push(skill.instructions);
-      }
-      if (skill.toolNames.length > 0) {
-        lines.push("");
-        lines.push(`**Tools:** ${skill.toolNames.join(", ")}`);
-      }
-      lines.push("");
-    }
   }
   return lines.join("\n");
 }
 async function handleInitSkilder(_args, ctx) {
+  if (!ctx.catalog) {
+    ctx.logger.warn(
+      { userId: ctx.identity.id },
+      "init_skilder called with null catalog \u2014 catalog may not have loaded yet"
+    );
+  } else if (ctx.catalog.hats.length === 0) {
+    ctx.logger.warn(
+      { userId: ctx.identity.id, skillCount: ctx.catalog.skills.length },
+      "init_skilder called with no hats in catalog"
+    );
+  }
   return {
     response: { content: [{ type: "text", text: buildInitSkilderResponse(ctx) }] }
   };
@@ -144785,86 +144710,75 @@ function errorResult(text2, skillIds) {
 }
 
 // src/services/static-tools/learn.handler.ts
-function appendReferencedResources(lines, mentions, skillName, heading) {
+function appendReferencedResources(lines, mentions, related, skillName) {
   if (mentions.length === 0) return;
-  lines.push(`## ${heading}`);
+  lines.push("## Resources");
+  lines.push("Only resources referenced in the skill description or instructions are shown.");
+  lines.push("");
   for (const m2 of mentions) {
     const resourcePath = `/${skillName}/${m2.qualifiedName}`;
+    const entry = related.find((r2) => (r2.path ? `${r2.path}/${r2.name}` : r2.name) === m2.qualifiedName);
+    lines.push(`### ${m2.name}`);
+    if (entry?.description) {
+      lines.push(entry.description);
+    }
+    lines.push("");
     if (m2.class === "learnable") {
-      lines.push(`- To learn more about \`${m2.qualifiedName}\`: \`learn --path "${resourcePath}"\``);
+      lines.push(`**Consume:** \`learn --path "${resourcePath}"\``);
     } else if (m2.class === "executable") {
-      lines.push(`- To execute \`${m2.qualifiedName}\`: \`execute_script --path "${resourcePath}"\``);
+      lines.push(`**Consume:** \`execute_script --path "${resourcePath}"\``);
     } else {
-      lines.push(`- To download \`${m2.qualifiedName}\`: \`download_asset --path "${resourcePath}"\``);
+      lines.push(`**Consume:** \`download_asset --path "${resourcePath}"\``);
     }
+    lines.push("");
   }
 }
-function formatSkillDetails(skill, ctx, options) {
-  const headingLevel = options?.headingLevel ?? 2;
-  const heading = "#".repeat(headingLevel);
-  const renderedToolNames = options?.renderedToolNames;
-  const firstSkillForTool = options?.firstSkillForTool;
+function formatSkillDetails(skill, ctx) {
   const lines = [];
   if (skill.description) {
     lines.push(skill.description);
     lines.push("");
   }
   if (skill.instructions) {
-    lines.push(`${heading} Instructions`);
+    lines.push("## Instructions");
     lines.push(skill.instructions);
     lines.push("");
   }
   if (skill.toolNames.length > 0) {
-    lines.push(`${heading} Available Tools`);
+    lines.push("## Available Tools");
     lines.push("Use `call_tool` with the tool name and input to execute these tools:");
     lines.push("");
     for (const toolName of skill.toolNames) {
-      const subHeading = "#".repeat(headingLevel + 1);
-      if (renderedToolNames?.has(toolName)) {
-        const firstSkill = firstSkillForTool?.get(toolName);
-        lines.push(`${subHeading} ${toolName}`);
-        lines.push(firstSkill ? `(schema shown above under ${firstSkill})` : "(schema shown above)");
+      const tool2 = ctx.getTools()?.find((t4) => t4.name === toolName);
+      if (tool2) {
+        lines.push(`### ${tool2.name}`);
+        lines.push(tool2.description || "No description");
+        lines.push("");
+        lines.push("**Input Schema:**");
+        lines.push("```json");
+        lines.push(JSON.stringify(tool2.inputSchema, null, 2));
+        lines.push("```");
         lines.push("");
       } else {
-        if (renderedToolNames) {
-          renderedToolNames.add(toolName);
-          firstSkillForTool?.set(toolName, skill.name);
-        }
-        const tool2 = ctx.getTools()?.find((t4) => t4.name === toolName);
-        if (tool2) {
-          lines.push(`${subHeading} ${tool2.name}`);
-          lines.push(tool2.description || "No description");
-          lines.push("");
-          lines.push("**Input Schema:**");
-          lines.push("```json");
-          lines.push(JSON.stringify(tool2.inputSchema, null, 2));
-          lines.push("```");
-          lines.push("");
-        } else {
-          ctx.logger.warn(
-            { toolName, skillId: skill.id, toolsInitialized: ctx.getTools() != null },
-            `Tool "${toolName}" referenced by skill "${skill.name}" not found in tools list`
-          );
-          lines.push(`${subHeading} ${toolName}`);
-          lines.push("Tool definition not available");
-          lines.push("");
-        }
+        ctx.logger.warn(
+          { toolName, skillId: skill.id, toolsInitialized: ctx.getTools() != null },
+          `Tool "${toolName}" referenced by skill "${skill.name}" not found in tools list`
+        );
+        lines.push(`### ${toolName}`);
+        lines.push("Tool definition not available");
+        lines.push("");
       }
     }
     lines.push('Call these tools using: `call_tool(tool_name="<name>", tool_input={...})`');
   } else {
     lines.push("This skill provides instructions only and has no associated tools.");
   }
-  if (skill.instructions && skill.related.length > 0) {
-    try {
-      const mentions = detectRelatedMentions(skill.instructions, skill.related);
+  if (skill.related.length > 0) {
+    const sourceText = [skill.description, skill.instructions].filter(Boolean).join("\n\n");
+    const mentions = detectRelatedMentions(sourceText, skill.related);
+    if (mentions.length > 0) {
       lines.push("");
-      appendReferencedResources(lines, mentions, skill.name, "Resources Referenced in Instructions");
-    } catch (error48) {
-      ctx.logger.error(
-        { err: error48, skillId: skill.id, skillName: skill.name },
-        "Failed to detect related mentions in skill instructions \u2014 skipping resource list"
-      );
+      appendReferencedResources(lines, mentions, skill.related, skill.name);
     }
   }
   return lines;
@@ -144912,9 +144826,9 @@ function handleGetHat(hatName, ctx) {
       missingSkillIds.push(skillId);
     }
   }
-  const totalToolCount = new Set(skills.flatMap((s) => s.toolNames)).size;
   ctx.logger.info(
-    `User ${ctx.identity.id} retrieved hat "${hat.name}" with ${skills.length} skills and ${totalToolCount} tools`
+    { userId: ctx.identity.id, hatId: hat.id, hatName: hat.name, skillCount: skills.length },
+    "User retrieved hat"
   );
   const lines = [];
   lines.push(`# Hat: ${hat.name}`);
@@ -144929,13 +144843,16 @@ function handleGetHat(hatName, ctx) {
     lines.push("");
   }
   if (skills.length > 0) {
-    lines.push("## Skills Learned");
+    lines.push("## Available Skills");
+    lines.push('Use `learn --path "/Skill Name"` to learn a skill and unlock its tools and resources.');
     lines.push("");
-    const renderedToolNames = /* @__PURE__ */ new Set();
-    const firstSkillForTool = /* @__PURE__ */ new Map();
     for (const skill of skills) {
       lines.push(`### ${skill.name}`);
-      lines.push(...formatSkillDetails(skill, ctx, { headingLevel: 4, renderedToolNames, firstSkillForTool }));
+      if (skill.description) {
+        lines.push(skill.description);
+      }
+      lines.push("");
+      lines.push(`**Learn this skill:** \`learn --path "/${skill.name}"\``);
       lines.push("");
     }
   } else {
@@ -144950,7 +144867,7 @@ function handleGetHat(hatName, ctx) {
   }
   return {
     response: { content: [{ type: "text", text: lines.join("\n") }] },
-    skillIds: hat.skillIds
+    skillIds: []
   };
 }
 async function handleGetRelated(skillName, resourceName, ctx) {
@@ -144993,14 +144910,32 @@ To execute this script, use:
     lines.push(`**Description:** ${item.description}`);
   }
   lines.push("");
-  if (ctx.skillContentService && ctx.identity.userKey) {
+  if (!ctx.skillContentService) {
+    ctx.logger.error(
+      { resourceId: item.id, skillId: skill.id },
+      "skillContentService not injected \u2014 cannot fetch resource content"
+    );
+    lines.push("*Content unavailable: this runtime is not configured to fetch resource content.*");
+  } else if (!ctx.identity.userKey) {
+    ctx.logger.error(
+      { resourceId: item.id, skillId: skill.id, userId: ctx.identity.id },
+      "userKey missing \u2014 cannot authenticate resource content fetch"
+    );
+    lines.push("*Content unavailable: authentication context is missing. Please reconnect.*");
+  } else {
     try {
       const content = await ctx.skillContentService.getContent(item.id, ctx.identity.userKey);
-      if (content) {
-        lines.push(content);
-      } else {
-        lines.push("*No content available for this resource.*");
+      if (content == null) {
+        ctx.logger.error(
+          { resourceId: item.id, resourceName: item.name, skillId: skill.id },
+          "skillContentService.getContent returned null \u2014 no content for resource"
+        );
+        return errorResult(
+          `Error: No content found for resource "${item.name}". The resource may be empty or unavailable.`,
+          [skill.id]
+        );
       }
+      lines.push(content);
     } catch (err) {
       ctx.logger.error({ err, resourceId: item.id }, "Failed to fetch resource content");
       return errorResult(
@@ -145008,8 +144943,6 @@ To execute this script, use:
         [skill.id]
       );
     }
-  } else {
-    lines.push("*Content unavailable: this runtime is not configured to fetch resource content.*");
   }
   return {
     response: { content: [{ type: "text", text: lines.join("\n") }] },