@theokit/sdk-tools 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -332,12 +332,26 @@ declare function catastrophicShellReason(command: string): string | null;
  * name/inputSchema/handler; does NOT mutate the original tool.
  */
 declare function withDescription(tool: CustomTool, description: string): CustomTool;
-/**
- * Render a `<tools>` block (name + description per tool) from the agent's actual
- * `CustomTool[]` — single source of truth, so an overridden/added/removed tool
- * is reflected automatically. An empty array yields `<tools></tools>`. Never throws.
- */
-declare function renderToolList(tools: CustomTool[]): string;
+/** Render mode for {@link renderToolList}. Local — the published `renderToolList`
+ *  signature inlines this union into its `.d.ts`, so consumers pass the literal
+ *  ("summary" | "names" | "full") without needing the named type exported. */
+type ToolListMode = "full" | "summary" | "names";
+/**
+ * Render the agent's actual `CustomTool[]` — single source of truth, so an
+ * overridden/added/removed tool is reflected automatically. Never throws.
+ *
+ * Modes (`options.mode`, default `"full"`):
+ * - `"full"`: a `<tools>` XML block (name + description per tool, XML-escaped).
+ *   An empty array yields `<tools></tools>`.
+ * - `"summary"`: markdown `- name: <first sentence>` per tool (NOT XML-escaped).
+ * - `"names"`: markdown `- name` per tool (NOT XML-escaped).
+ *
+ * Markdown modes on an empty array yield `""`. A non-object `options` arg (e.g. a
+ * map index from `tools.map(renderToolList)`) has no `.mode` → falls back to `"full"`.
+ */
+declare function renderToolList(tools: CustomTool[], options?: {
+    mode?: ToolListMode;
+}): string;
 
 /**
  * Rich-error guidance for tool failures (M3-4).

package/dist/index.d.ts

@@ -332,12 +332,26 @@ declare function catastrophicShellReason(command: string): string | null;
  * name/inputSchema/handler; does NOT mutate the original tool.
  */
 declare function withDescription(tool: CustomTool, description: string): CustomTool;
-/**
- * Render a `<tools>` block (name + description per tool) from the agent's actual
- * `CustomTool[]` — single source of truth, so an overridden/added/removed tool
- * is reflected automatically. An empty array yields `<tools></tools>`. Never throws.
- */
-declare function renderToolList(tools: CustomTool[]): string;
+/** Render mode for {@link renderToolList}. Local — the published `renderToolList`
+ *  signature inlines this union into its `.d.ts`, so consumers pass the literal
+ *  ("summary" | "names" | "full") without needing the named type exported. */
+type ToolListMode = "full" | "summary" | "names";
+/**
+ * Render the agent's actual `CustomTool[]` — single source of truth, so an
+ * overridden/added/removed tool is reflected automatically. Never throws.
+ *
+ * Modes (`options.mode`, default `"full"`):
+ * - `"full"`: a `<tools>` XML block (name + description per tool, XML-escaped).
+ *   An empty array yields `<tools></tools>`.
+ * - `"summary"`: markdown `- name: <first sentence>` per tool (NOT XML-escaped).
+ * - `"names"`: markdown `- name` per tool (NOT XML-escaped).
+ *
+ * Markdown modes on an empty array yield `""`. A non-object `options` arg (e.g. a
+ * map index from `tools.map(renderToolList)`) has no `.mode` → falls back to `"full"`.
+ */
+declare function renderToolList(tools: CustomTool[], options?: {
+    mode?: ToolListMode;
+}): string;
 
 /**
  * Rich-error guidance for tool failures (M3-4).

package/dist/index.js

@@ -979,7 +979,18 @@ function withDescription(tool, description) {
 function esc(s) {
   return String(s).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
-function renderToolList(tools) {
+function firstSentence(d) {
+  const m = d.trim().match(/\.\s+(?=[A-Z(]|$)/);
+  return m?.index == null ? d.trim() : d.trim().slice(0, m.index + 1);
+}
+function renderToolList(tools, options) {
+  const mode = options?.mode ?? "full";
+  if (mode === "summary") {
+    return tools.map((t) => `- ${t.name}: ${firstSentence(t.description)}`).join("\n");
+  }
+  if (mode === "names") {
+    return tools.map((t) => `- ${t.name}`).join("\n");
+  }
   if (tools.length === 0) return "<tools></tools>";
   const lines = ["<tools>"];
   for (const t of tools) {