@cognipeer/agent-sdk 0.8.3 → 0.8.5

package/dist/index.cjs

@@ -4573,6 +4573,7 @@ function resolveUserQuestionState(state, resolution) {
     ctx
   };
 }
+var ASK_USER_TOOL_NAME = "ask_user_question";
 var DEFAULT_DESCRIPTION_WITH_FREETEXT = "Pause the agent and surface a structured prompt to the human user when you genuinely cannot proceed without their input. Group up to 4 closely related questions into a single call. Prefer concrete options the user can pick over open-ended free-text \u2014 list `options` whenever you can anticipate the choices. The user may type a custom answer for any question. Do not use this tool for things you can deduce from the conversation, the system prompt, or another tool. After the user answers, their selections come back as the tool result.";
 var DEFAULT_DESCRIPTION_NO_FREETEXT = "Pause the agent and surface a structured multi-choice prompt to the human user when you genuinely cannot proceed without their input. Group up to 4 closely related questions into a single call. Every question MUST include at least two `options` \u2014 free-text answers are disabled for this agent. Do not use this tool for things you can deduce from the conversation, the system prompt, or another tool. After the user picks, their selections come back as the tool result.";
 function buildOptionSchema() {
@@ -4608,7 +4609,7 @@ function createAskUserQuestionTool(stateRef, config) {
   const description = config.promptOverride ?? (allowFreeText ? DEFAULT_DESCRIPTION_WITH_FREETEXT : DEFAULT_DESCRIPTION_NO_FREETEXT);
   const questionSchema = buildQuestionSchema(allowFreeText);
   const askUser = createTool({
-    name: "ask_user_question",
+    name: ASK_USER_TOOL_NAME,
     description,
     schema: zod.z.object({
       questions: zod.z.array(questionSchema).min(1).max(4).describe("1-4 related questions to ask in a single pause.")
@@ -4624,7 +4625,7 @@ function createAskUserQuestionTool(stateRef, config) {
       const entry = {
         id: nanoid.nanoid(),
         toolCallId,
-        toolName: "ask_user_question",
+        toolName: ASK_USER_TOOL_NAME,
         questions,
         status: "pending",
         requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -4980,14 +4981,15 @@ function createAgent(opts) {
   })();
   const askUserOnQuestion = typeof opts.humanInTheLoop?.askUser === "object" ? opts.humanInTheLoop?.askUser?.onQuestion : void 0;
   const askUserStateRef = askUserConfig ? { pendingUserQuestions: void 0, ctx: void 0, __onEvent: void 0, __currentToolCallId: void 0 } : void 0;
-  if (askUserConfig && askUserStateRef) {
+  const hasTool = (name) => toolsBase.some((tool) => tool?.name === name);
+  if (askUserConfig && askUserStateRef && !hasTool(ASK_USER_TOOL_NAME)) {
     toolsBase.push(createAskUserQuestionTool(askUserStateRef, askUserConfig));
   }
   const soManager = opts.outputSchema ? new StructuredOutputManager(opts.outputSchema, resolveStrategy(opts.model)) : void 0;
   if (soManager) {
     const modelCapabilities = getModelCapabilities(opts.model);
     const responseTool = soManager.getResponseTool();
-    if (responseTool && modelCapabilities.structuredOutput !== "native") {
+    if (responseTool && modelCapabilities.structuredOutput !== "native" && !hasTool(responseTool.name)) {
       toolsBase.push(responseTool);
     }
   }
@@ -6920,6 +6922,42 @@ async function resolveAvailableSkills(skills, opts = {}) {
   }
   return out;
 }
+var WORD_SPLIT = /[^\p{L}\p{N}]+/u;
+var MIN_TERM_LENGTH = 3;
+var FIELD_WEIGHTS = { key: 4, title: 3, header: 2 };
+var wordsOf = (text) => text.toLowerCase().split(WORD_SPLIT).filter((word) => word.length >= 2);
+var termHitsWord = (term, word) => word === term || word.startsWith(term) || word.length >= 3 && term.startsWith(word) || term.length >= 5 && word.length >= 5 && word.slice(0, 4) === term.slice(0, 4);
+function searchSkills(skills, query, limit = 10) {
+  const cap = Math.max(1, limit);
+  const normalized = (query || "").trim().toLowerCase();
+  const terms = [
+    ...new Set(normalized.split(WORD_SPLIT).filter((term) => term.length >= MIN_TERM_LENGTH))
+  ];
+  if (terms.length === 0) return skills.slice(0, cap);
+  const scored = skills.map((skill, index) => {
+    const fields = {
+      key: wordsOf(skill.key),
+      title: wordsOf(skill.title || ""),
+      header: wordsOf(skill.header || "")
+    };
+    const exact = skill.key.toLowerCase() === normalized || (skill.title || "").toLowerCase() === normalized;
+    let score = exact ? 100 : 0;
+    let coverage = 0;
+    for (const term of terms) {
+      let hit = false;
+      for (const [field, weight] of Object.entries(FIELD_WEIGHTS)) {
+        if (fields[field].some((word) => termHitsWord(term, word))) {
+          score += weight;
+          hit = true;
+        }
+      }
+      if (hit) coverage += 1;
+    }
+    return { skill, score, coverage, index };
+  }).filter((entry) => entry.score > 0);
+  scored.sort((a, b) => b.coverage - a.coverage || b.score - a.score || a.index - b.index);
+  return scored.slice(0, cap).map((entry) => entry.skill);
+}
 function buildSkillHeaderBlock(skills) {
   if (skills.length === 0) return "";
   const lines = skills.map((skill) => `- ${skill.key}: ${skill.header}`);
@@ -6943,24 +6981,65 @@ function dedupeToolsByName(tools) {
 
 // src/smart/skills/skillTools.ts
 var MAX_RETURNED_INDEX = 40;
-var OPEN_SKILL_DESCRIPTION = "Load a capability on demand. Pass a skillKey from <available_skills>. A small skill binds all its tools immediately; a large one returns a tool index \u2014 then call bind_skill_tools with only the tools you need. Open only what the task needs.";
+var DEFAULT_SEARCH_LIMIT = 10;
+var MAX_SEARCH_LIMIT = 25;
+var isSearchDisclosure = (policy) => policy.disclosure === "search";
+var keySource = (policy) => isSearchDisclosure(policy) ? "search_skills" : "<available_skills>";
+var openSkillDescription = (policy) => `Load a capability on demand. Pass a skillKey from ${keySource(policy)}. A small skill binds all its tools immediately; a large one returns a tool index \u2014 then call bind_skill_tools with only the tools you need. Open only what the task needs.`;
 var BIND_SKILL_TOOLS_DESCRIPTION = "After open_skill on a large skill, bind a chosen subset of its tools by name. Pick the few tools the task actually needs.";
+var SEARCH_SKILLS_DESCRIPTION = 'Find a reusable playbook (a "skill") for the task at hand. Skills are proven, pre-written procedures for specific kinds of work \u2014 each with its own tools, which are NOT in your tool list until you open the skill. Call this early whenever a request looks like an established procedure, or when you seem to be missing a capability you would expect to have: describe the task in `query`. Returns matching skill keys; pass one to open_skill to load its instructions and tools. An empty query lists what exists.';
 function findSkill(deps, key) {
   return deps.skills.find((skill) => skill.key === key);
 }
+function createSearchSkillsTool(deps) {
+  const tool = createTool({
+    name: "search_skills",
+    description: SEARCH_SKILLS_DESCRIPTION,
+    schema: zod.z.object({
+      query: zod.z.string().optional().describe("What you are trying to do, in a few words. Omit to list available skills."),
+      limit: zod.z.number().int().positive().optional().describe(`Max results to return (default ${DEFAULT_SEARCH_LIMIT}).`)
+    }).strict(),
+    func: async ({ query, limit }) => {
+      const { skills, policy, registryRef: ref } = tool._deps;
+      const available = await resolveAvailableSkills(skills, { modelTier: policy.modelTier });
+      if (available.length === 0) {
+        return { skills: [], total: 0, hint: "No skills are available in this workspace." };
+      }
+      const capped = Math.min(limit || DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
+      const matches = searchSkills(available, query, capped);
+      const missed = matches.length === 0;
+      const shown = missed ? available.slice(0, capped) : matches;
+      return {
+        skills: shown.map((skill) => ({
+          skillKey: skill.key,
+          title: skill.title,
+          header: skill.header,
+          ...ref.openedSkillKeys.includes(skill.key) ? { alreadyOpen: true } : {}
+        })),
+        total: available.length,
+        hint: missed ? `Nothing matched "${query}" literally \u2014 listing ${shown.length} of ${available.length} instead. Judge them by their headers; call open_skill(skillKey) if one fits, otherwise carry on without a skill.` : "Call open_skill(skillKey) to load the one that fits."
+      };
+    }
+  });
+  tool._deps = deps;
+  tool.__source = "smart-skills";
+  return tool;
+}
 function createOpenSkillTool(deps) {
   const tool = createTool({
     name: "open_skill",
-    description: OPEN_SKILL_DESCRIPTION,
+    description: openSkillDescription(deps.policy),
     schema: zod.z.object({
-      skillKey: zod.z.string().min(1).describe("A key from <available_skills>."),
+      skillKey: zod.z.string().min(1).describe(`A key from ${keySource(deps.policy)}.`),
       query: zod.z.string().optional().describe("What you need from the skill \u2014 used to rank a large skill's tools.")
     }).strict(),
     func: async ({ skillKey, query }) => {
       const { registryRef: ref, policy } = tool._deps;
       const skill = findSkill(tool._deps, skillKey);
       if (!skill) {
-        return { error: `Unknown skill: ${skillKey}. Choose a key listed in <available_skills>.` };
+        return {
+          error: `Unknown skill: ${skillKey}. ${isSearchDisclosure(policy) ? "Call search_skills to get a valid key." : "Choose a key listed in <available_skills>."}`
+        };
       }
       if (skill.isAvailable && !await skill.isAvailable()) {
         return { error: `Skill ${skillKey} is not available in this workspace.` };
@@ -7049,7 +7128,9 @@ function createBindSkillToolsTool(deps) {
   return tool;
 }
 function createSkillTools(deps) {
-  return [createOpenSkillTool(deps), createBindSkillToolsTool(deps)];
+  const tools = [createOpenSkillTool(deps), createBindSkillToolsTool(deps)];
+  if (isSearchDisclosure(deps.policy)) tools.unshift(createSearchSkillsTool(deps));
+  return tools;
 }
 
 // src/smart/subagents/types.ts
@@ -7729,7 +7810,8 @@ function createSmartAgent(opts) {
         if (changed) toolSet.skillRegistryRef.__onToolsChanged?.();
       }
       const syncPlanFromRef = (state2) => syncPlanStateWith(stateRef, state2);
-      const availableSkills = skillsEnabled ? await resolveAvailableSkills(skills, { modelTier: skillPolicy.modelTier }) : [];
+      const catalogDisclosure = skillPolicy.disclosure !== "search";
+      const availableSkills = skillsEnabled && catalogDisclosure ? await resolveAvailableSkills(skills, { modelTier: skillPolicy.modelTier }) : [];
       const skillBlock = availableSkills.length > 0 ? buildSkillHeaderBlock(availableSkills) : void 0;
       let subagentBlock;
       if (subagentsEnabled) {
@@ -10947,6 +11029,7 @@ function createProvider(config) {
   }
 }
 
+exports.ASK_USER_TOOL_NAME = ASK_USER_TOOL_NAME;
 exports.AnthropicProvider = AnthropicProvider;
 exports.AzureProvider = AzureProvider;
 exports.BaseProvider = BaseProvider;
@@ -11005,6 +11088,7 @@ exports.createParallelTool = createParallelTool;
 exports.createProvider = createProvider;
 exports.createRegexGuardrail = createRegexGuardrail;
 exports.createResolverNode = createResolverNode;
+exports.createSearchSkillsTool = createSearchSkillsTool;
 exports.createSkillRegistryRef = createSkillRegistryRef;
 exports.createSkillTools = createSkillTools;
 exports.createSmartAgent = createSmartAgent;
@@ -11056,6 +11140,7 @@ exports.resolveUserQuestionState = resolveUserQuestionState;
 exports.restoreSnapshot = restoreSnapshot;
 exports.runSmartAgentEvalHarness = runSmartAgentEvalHarness;
 exports.scoreItemsByRelevance = scoreItemsByRelevance;
+exports.searchSkills = searchSkills;
 exports.seedChildMessages = seedChildMessages;
 exports.selectTopIndicesInOrder = selectTopIndicesInOrder;
 exports.setTokenCounter = setTokenCounter;