@cognipeer/agent-sdk 0.7.1 → 0.7.2

package/README.md

@@ -36,6 +36,7 @@ Highlights:
 - **Planning mode** – adaptive system prompt + TODO tool supports full plan writes and version-safe partial updates.
 - **Unified reasoning surface** – one `reasoning` config controls provider-native reasoning and post-tool plain-text reflections.
 - **Structured output** – provide a Zod schema and the agent injects a finalize tool to capture JSON deterministically.
+- **Skills / progressive disclosure** – expose cheap capability headers first, then bind skill tools on demand with `open_skill` and `bind_skill_tools`.
 - **Multi-agent and handoffs** – wrap agents as tools or transfer control mid-run with `asTool` / `asHandoff`.
 - **Human-in-the-loop** – `needsApproval` tools pause for review; `humanInTheLoop.askUser` enables a built-in `ask_user_question` tool that pauses with a structured multi-choice prompt and resumes from the user's answer.
 - **Usage + events** – normalize provider usage, surface `tool_call`, `tool_approval`, `user_question`, `plan`, `summarization`, `reflection`, `metadata`, and `handoff` events.
@@ -165,7 +166,33 @@ Tool-response retention is lazy and summarizer-driven:
 - `criticalTools` are never reduced. The built-in list covers `response`, `manage_todo_list`, and `get_tool_response`.
 - `maxToolResponseChars` / `maxToolResponseTokens` only drive an eager hard-cap truncation when a single tool output is big enough to blow up the very next model call. The truncated head always points at `get_tool_response` for recovery.
 
-The smart wrapper now supports runtime presets (`fast`, `balanced`, `deep`, `research`), custom profiles layered on top of a base preset, structured summarization, hybrid context compaction, configurable tool-response retention, in-memory fact storage, delegation limits, and an eval harness via `runSmartAgentEvalHarness(...)`.
+The smart wrapper now supports runtime presets (`fast`, `balanced`, `deep`, `research`), custom profiles layered on top of a base preset, structured summarization, hybrid context compaction, skill-based progressive disclosure, configurable tool-response retention, in-memory fact storage, delegation limits, and an eval harness via `runSmartAgentEvalHarness(...)`.
+
+For large or optional tool catalogs, pass `skills` instead of binding every tool directly:
+
+```ts
+import { createSmartAgent, type Skill } from "@cognipeer/agent-sdk";
+
+const pdfSkill: Skill = {
+  key: "builtin:pdf",
+  title: "PDF",
+  header: "read and summarize PDF files when the user references a PDF",
+  prompt: "Use pdf_read before pdf_summarize and preserve file ids in the answer.",
+  listToolIndex: () => [
+    { name: "pdf_read", description: "Extract PDF text by file id" },
+    { name: "pdf_summarize", description: "Summarize extracted PDF text" },
+  ],
+  bindTools: (names) => bindPdfTools(names),
+};
+
+const agent = createSmartAgent({
+  model,
+  skills: [pdfSkill],
+  skillPolicy: { maxOpenSkills: 2, maxBoundToolsPerSkill: 8, maxBoundToolsTotal: 24 },
+});
+```
+
+The model sees the skill header first. It calls `open_skill` to load the skill prompt and either bind a small skill immediately or get a tool index for `bind_skill_tools`.
 
 You can also define a custom profile by extending a built-in preset and overriding only the knobs you need:
 

package/dist/index.cjs

@@ -3036,6 +3036,17 @@ function createToolsNode(initialTools, opts) {
         }
         const durationMs = Date.now() - start;
         const executionId = nanoid.nanoid();
+        if (output && typeof output === "object" && Array.isArray(output.__runtimeToolsDelta)) {
+          const delta = output.__runtimeToolsDelta;
+          delete output.__runtimeToolsDelta;
+          const currentRuntime = state.agent || runtime;
+          const currentTools = currentRuntime?.tools ?? [];
+          const present = new Set(currentTools.map((tool2) => tool2?.name));
+          const additions = delta.filter((tool2) => tool2 && tool2.name && !present.has(tool2.name));
+          if (additions.length > 0 && currentRuntime) {
+            state.agent = { ...currentRuntime, tools: [...currentTools, ...additions] };
+          }
+        }
         if (output && typeof output === "object" && output.__handoff && output.__handoff.runtime) {
           toolHistory.push({ executionId, toolName, args, output: "handoff:ok", rawOutput: output, timestamp: (/* @__PURE__ */ new Date()).toISOString(), tool_call_id: tc.id, status: "handoff" });
           push({ role: "tool", content: "ok", tool_call_id: tc.id || `${tc.name}_${toolCount}`, name: tc.name });
@@ -6193,6 +6204,190 @@ async function writeSummaryFactsToMemory(store, config, summary, sourceTurn) {
   return store.get(config.memory.scope, { limit: config.context.lastTurnsToKeep + summary.stable_facts.length });
 }
 
+// src/smart/skills/types.ts
+var DEFAULT_SKILL_POLICY = {
+  maxOpenSkills: 4,
+  maxBoundToolsPerSkill: 12,
+  maxBoundToolsTotal: 40
+};
+var SMALL_TIER_SKILL_POLICY = {
+  maxOpenSkills: 1,
+  maxBoundToolsPerSkill: 6,
+  maxBoundToolsTotal: 18,
+  modelTier: "small"
+};
+function createSkillRegistryRef() {
+  return { openedSkillKeys: [], boundSkillTools: [] };
+}
+
+// src/smart/skills/registry.ts
+function composeToolSets(input) {
+  const without = [...input.base, ...input.boundSkillTools];
+  const withRec = input.recoveryTool ? [...without, input.recoveryTool] : [...without];
+  return { toolsWithoutRecovery: without, toolsWithRecovery: withRec };
+}
+function appendBoundTools(ref, newTools, policy) {
+  const present = new Set(ref.boundSkillTools.map((tool) => tool.name));
+  const added = [];
+  for (const tool of newTools) {
+    if (ref.boundSkillTools.length >= policy.maxBoundToolsTotal) break;
+    if (present.has(tool.name)) continue;
+    present.add(tool.name);
+    ref.boundSkillTools.push(tool);
+    added.push(tool);
+  }
+  return added;
+}
+function canOpenSkill(ref, policy) {
+  if (ref.openedSkillKeys.length >= policy.maxOpenSkills) {
+    return { ok: false, reason: `max ${policy.maxOpenSkills} skill(s) already open` };
+  }
+  if (ref.boundSkillTools.length >= policy.maxBoundToolsTotal) {
+    return { ok: false, reason: "skill tool budget exhausted" };
+  }
+  return { ok: true };
+}
+async function resolveAvailableSkills(skills, opts = {}) {
+  const out = [];
+  for (const skill of skills) {
+    if (skill.minModelTier === "large" && opts.modelTier === "small") continue;
+    const available = skill.isAvailable ? await skill.isAvailable() : true;
+    if (available) out.push(skill);
+  }
+  return out;
+}
+function buildSkillHeaderBlock(skills) {
+  if (skills.length === 0) return "";
+  const lines = skills.map((skill) => `- ${skill.key}: ${skill.header}`);
+  return [
+    "<available_skills>",
+    "Open a skill with open_skill(skillKey) to load its tools on demand. Only open what the task needs; close nothing \u2014 opened skills stay available for the rest of the run.",
+    ...lines,
+    "</available_skills>"
+  ].join("\n");
+}
+function dedupeToolsByName(tools) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const tool of tools) {
+    if (seen.has(tool.name)) continue;
+    seen.add(tool.name);
+    out.push(tool);
+  }
+  return out;
+}
+
+// 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 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.";
+function findSkill(deps, key) {
+  return deps.skills.find((skill) => skill.key === key);
+}
+function createOpenSkillTool(deps) {
+  const tool = createTool({
+    name: "open_skill",
+    description: OPEN_SKILL_DESCRIPTION,
+    schema: zod.z.object({
+      skillKey: zod.z.string().min(1).describe("A key from <available_skills>."),
+      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>.` };
+      }
+      if (skill.isAvailable && !await skill.isAvailable()) {
+        return { error: `Skill ${skillKey} is not available in this workspace.` };
+      }
+      const alreadyOpen = ref.openedSkillKeys.includes(skillKey);
+      if (!alreadyOpen) {
+        const guard = canOpenSkill(ref, policy);
+        if (!guard.ok) {
+          return {
+            error: `Cannot open ${skillKey}: ${guard.reason}. Work with the skills already open.`
+          };
+        }
+        ref.openedSkillKeys.push(skillKey);
+      }
+      const prompt = typeof skill.prompt === "function" ? await skill.prompt() : skill.prompt;
+      const index = await skill.listToolIndex();
+      if (index.length <= policy.maxBoundToolsPerSkill) {
+        const bound = await skill.bindTools();
+        const added = appendBoundTools(ref, bound, policy);
+        if (added.length > 0) ref.__onToolsChanged?.();
+        return {
+          skillKey,
+          prompt,
+          needsSandbox: Boolean(skill.needsSandbox),
+          boundTools: added.map((t) => t.name),
+          // Inject the bound tools into the live runtime for this loop.
+          __runtimeToolsDelta: added
+        };
+      }
+      let defaultBound = [];
+      let defaultAdded = [];
+      if ((!query || query.trim().length < 3) && skill.defaultBindNames?.length) {
+        const bound = await skill.bindTools(skill.defaultBindNames.slice(0, policy.maxBoundToolsPerSkill));
+        defaultAdded = appendBoundTools(ref, bound, policy);
+        if (defaultAdded.length > 0) ref.__onToolsChanged?.();
+        defaultBound = defaultAdded.map((t) => t.name);
+      }
+      const headers = query && query.trim().length >= 3 && skill.rankToolHeaders ? await skill.rankToolHeaders(query, index) : index;
+      return {
+        skillKey,
+        prompt,
+        needsSandbox: Boolean(skill.needsSandbox),
+        boundTools: defaultBound,
+        toolIndex: headers.slice(0, MAX_RETURNED_INDEX).map((h) => ({ name: h.name, description: h.description })),
+        hint: "Call bind_skill_tools(skillKey, toolNames) with only the tools you need.",
+        ...defaultAdded.length > 0 ? { __runtimeToolsDelta: defaultAdded } : {}
+      };
+    }
+  });
+  tool._deps = deps;
+  tool.__source = "smart-skills";
+  return tool;
+}
+function createBindSkillToolsTool(deps) {
+  const tool = createTool({
+    name: "bind_skill_tools",
+    description: BIND_SKILL_TOOLS_DESCRIPTION,
+    schema: zod.z.object({
+      skillKey: zod.z.string().min(1),
+      toolNames: zod.z.array(zod.z.string().min(1)).min(1).describe("Tool names from the skill's index.")
+    }).strict(),
+    func: async ({ skillKey, toolNames }) => {
+      const { registryRef: ref, policy } = tool._deps;
+      const skill = findSkill(tool._deps, skillKey);
+      if (!skill) {
+        return { error: `Unknown skill: ${skillKey}.` };
+      }
+      if (!ref.openedSkillKeys.includes(skillKey)) {
+        return { error: `Call open_skill("${skillKey}") before binding its tools.` };
+      }
+      const capped = toolNames.slice(0, policy.maxBoundToolsPerSkill);
+      const bound = await skill.bindTools(capped);
+      const added = appendBoundTools(ref, bound, policy);
+      if (added.length > 0) ref.__onToolsChanged?.();
+      return {
+        skillKey,
+        boundTools: added.map((t) => t.name),
+        requested: capped.length,
+        truncated: toolNames.length > capped.length,
+        ...added.length > 0 ? { __runtimeToolsDelta: added } : {}
+      };
+    }
+  });
+  tool._deps = deps;
+  tool.__source = "smart-skills";
+  return tool;
+}
+function createSkillTools(deps) {
+  return [createOpenSkillTool(deps), createBindSkillToolsTool(deps)];
+}
+
 // src/smart/index.ts
 function createSmartAgent(opts) {
   const resolved = normalizeSmartAgentOptions(opts);
@@ -6227,6 +6422,9 @@ function createSmartAgent(opts) {
   if (askUserConfig) {
     factoryToolsWithoutRecovery.push(createAskUserQuestionTool(factoryStateRef, askUserConfig));
   }
+  const skills = opts.skills ?? [];
+  const skillPolicy = opts.skillPolicy ?? DEFAULT_SKILL_POLICY;
+  const skillsEnabled = skills.length > 0;
   const soManagerFactory = opts.outputSchema ? new StructuredOutputManager(opts.outputSchema, resolveStrategy(opts.model)) : void 0;
   const modelCapabilities = opts.outputSchema ? getModelCapabilities(opts.model) : void 0;
   const responseFinalizeTool = soManagerFactory && modelCapabilities?.structuredOutput !== "native" ? soManagerFactory.getResponseTool() : void 0;
@@ -6234,12 +6432,31 @@ function createSmartAgent(opts) {
     const ref = { toolHistory: void 0, toolHistoryArchived: void 0, todoList: void 0, planVersion: 0, adherenceScore: 0 };
     const ctxTools = createContextTools(ref, { planningEnabled, includeGetToolResponse: false });
     const recoveryTool = createGetToolResponseTool(ref);
-    const base2 = [...userTools, ...ctxTools];
-    if (responseFinalizeTool) base2.push(responseFinalizeTool);
-    if (askUserConfig) base2.push(createAskUserQuestionTool(ref, askUserConfig));
-    const without = base2;
-    const withRec = [...without, recoveryTool];
-    return { stateRef: ref, toolsWithoutRecovery: without, toolsWithRecovery: withRec };
+    const coreBase = [...userTools, ...ctxTools];
+    if (responseFinalizeTool) coreBase.push(responseFinalizeTool);
+    if (askUserConfig) coreBase.push(createAskUserQuestionTool(ref, askUserConfig));
+    if (!skillsEnabled) {
+      const without = coreBase;
+      const withRec = [...without, recoveryTool];
+      return { stateRef: ref, toolsWithoutRecovery: without, toolsWithRecovery: withRec };
+    }
+    const toolSet = { stateRef: ref, toolsWithoutRecovery: [], toolsWithRecovery: [] };
+    const skillRegistryRef = createSkillRegistryRef();
+    const skillMetaTools = createSkillTools({ registryRef: skillRegistryRef, skills, policy: skillPolicy });
+    const baseWithMeta = [...coreBase, ...skillMetaTools];
+    const rebuild = () => {
+      const composed = composeToolSets({
+        base: baseWithMeta,
+        boundSkillTools: skillRegistryRef.boundSkillTools,
+        recoveryTool
+      });
+      toolSet.toolsWithoutRecovery = composed.toolsWithoutRecovery;
+      toolSet.toolsWithRecovery = composed.toolsWithRecovery;
+    };
+    skillRegistryRef.__onToolsChanged = rebuild;
+    toolSet.skillRegistryRef = skillRegistryRef;
+    rebuild();
+    return toolSet;
   };
   const base = createAgent({ ...runtimeOpts, tools: factoryToolsWithoutRecovery });
   base.__runtime.runtimeProfile = resolved.runtimeProfile;
@@ -6290,9 +6507,9 @@ function createSmartAgent(opts) {
       planVersion: ref.planVersion || state.planVersion || 1
     };
   }
-  function systemMessage2() {
+  function systemMessage2(extraBlock) {
     const sys = buildSystemPrompt(
-      [opts.systemPrompt, runtimeHint, structuredOutputHint].filter(Boolean).join("\n"),
+      [opts.systemPrompt, runtimeHint, structuredOutputHint, extraBlock].filter(Boolean).join("\n"),
       planningEnabled,
       opts.name || "Agent",
       opts.todoListPrompt
@@ -6342,8 +6559,10 @@ function createSmartAgent(opts) {
       stateRef.planVersion = input.planVersion || input.plan?.version || 0;
       stateRef.adherenceScore = input.plan?.adherenceScore || 0;
       const syncPlanFromRef = (state2) => syncPlanStateWith(stateRef, state2);
+      const availableSkills = skillsEnabled ? await resolveAvailableSkills(skills, { modelTier: skillPolicy.modelTier }) : [];
+      const skillBlock = availableSkills.length > 0 ? buildSkillHeaderBlock(availableSkills) : void 0;
       const alreadyHasSystem = Array.isArray(input.messages) && input.messages[0]?.role === "system";
-      const seedMessages = alreadyHasSystem ? [...input.messages || []] : [systemMessage2(), ...input.messages || []];
+      const seedMessages = alreadyHasSystem ? [...input.messages || []] : [systemMessage2(skillBlock), ...input.messages || []];
       let state = syncRuntimeTools(await syncMemory({ ...input, messages: seedMessages }), seedMessages, toolSet);
       let lastResult = null;
       let rawMessages = [...seedMessages];
@@ -9129,25 +9348,32 @@ exports.AzureProvider = AzureProvider;
 exports.BaseProvider = BaseProvider;
 exports.BedrockProvider = BedrockProvider;
 exports.DEFAULT_PROFILE_CONFIGS = DEFAULT_PROFILE_CONFIGS;
+exports.DEFAULT_SKILL_POLICY = DEFAULT_SKILL_POLICY;
 exports.GuardrailPhase = GuardrailPhase;
 exports.InMemoryMemoryStore = InMemoryMemoryStore;
 exports.NativeJsonSchemaStrategy = NativeJsonSchemaStrategy;
 exports.OpenAICompatibleProvider = OpenAICompatibleProvider;
 exports.OpenAIProvider = OpenAIProvider;
 exports.ProviderError = ProviderError;
+exports.SMALL_TIER_SKILL_POLICY = SMALL_TIER_SKILL_POLICY;
 exports.StructuredOutputManager = StructuredOutputManager;
 exports.ToolBasedStrategy = ToolBasedStrategy;
 exports.VertexProvider = VertexProvider;
 exports.agentVerdictRule = agentVerdictRule;
+exports.appendBoundTools = appendBoundTools;
+exports.buildSkillHeaderBlock = buildSkillHeaderBlock;
 exports.buildSystemPrompt = buildSystemPrompt;
+exports.canOpenSkill = canOpenSkill;
 exports.captureSnapshot = captureSnapshot;
 exports.codePresenceRule = codePresenceRule;
 exports.cognipeerSink = cognipeerSink;
+exports.composeToolSets = composeToolSets;
 exports.countApproxTokens = countApproxTokens;
 exports.countMessagesTokens = countMessagesTokens;
 exports.createAgent = createAgent;
 exports.createAgentNode = createAgentNode;
 exports.createAskUserQuestionTool = createAskUserQuestionTool;
+exports.createBindSkillToolsTool = createBindSkillToolsTool;
 exports.createCodeGuardrail = createCodeGuardrail;
 exports.createContextSummarizeNode = createContextSummarizeNode;
 exports.createContextTools = createContextTools;
@@ -9155,15 +9381,19 @@ exports.createGetToolResponseTool = createGetToolResponseTool;
 exports.createGuardrail = createGuardrail;
 exports.createJsonGuardrail = createJsonGuardrail;
 exports.createManageTodoTool = createManageTodoTool;
+exports.createOpenSkillTool = createOpenSkillTool;
 exports.createProvider = createProvider;
 exports.createRegexGuardrail = createRegexGuardrail;
 exports.createResolverNode = createResolverNode;
+exports.createSkillRegistryRef = createSkillRegistryRef;
+exports.createSkillTools = createSkillTools;
 exports.createSmartAgent = createSmartAgent;
 exports.createTool = createTool;
 exports.createToolLimitFinalizeNode = createToolLimitFinalizeNode;
 exports.createToolsNode = createToolsNode;
 exports.customCallbackRule = customCallbackRule;
 exports.customSink = customSink;
+exports.dedupeToolsByName = dedupeToolsByName;
 exports.defaultTokenCounter = defaultTokenCounter;
 exports.emptyUsage = emptyUsage;
 exports.evaluateGuardrails = evaluateGuardrails;
@@ -9186,6 +9416,7 @@ exports.normalizeSmartAgentOptions = normalizeSmartAgentOptions;
 exports.otlpSink = otlpSink;
 exports.readMemoryFacts = readMemoryFacts;
 exports.regexRule = regexRule;
+exports.resolveAvailableSkills = resolveAvailableSkills;
 exports.resolveMemoryStore = resolveMemoryStore;
 exports.resolveReasoning = resolveReasoning;
 exports.resolveStrategy = resolveStrategy;