la-machina-engine 0.19.7 → 0.20.0

package/dist/index.cjs

@@ -9078,6 +9078,123 @@ function describe(svc) {
     endpoints
   };
 }
+function describeEndpoint(ep) {
+  return {
+    method: ep.method,
+    path: ep.path,
+    description: ep.description,
+    ...ep.inputSchema !== void 0 ? { inputSchema: ep.inputSchema } : {},
+    ...ep.outputHint !== void 0 ? { outputHint: ep.outputHint } : {},
+    ...ep.pagination !== void 0 ? { pagination: ep.pagination } : {},
+    ...ep.response !== void 0 ? { response: ep.response } : {}
+  };
+}
+var DEFAULT_SEARCH_LIMIT = 8;
+var MAX_SEARCH_LIMIT = 20;
+var FIELD_WEIGHTS = {
+  path: 3,
+  method: 2,
+  description: 2,
+  inputKey: 1,
+  outputHint: 1,
+  response: 1
+};
+function tokenize(input) {
+  return input.toLowerCase().split(/[\s/_-]+/).map((t) => t.trim()).filter((t) => t.length > 0);
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function scoreEndpointMatch(ep, tokens, opts) {
+  let score = 0;
+  const matched = /* @__PURE__ */ new Set();
+  const pathLower = ep.path.toLowerCase();
+  const methodLower = ep.method.toLowerCase();
+  const descriptionLower = ep.description.toLowerCase();
+  const outputHintLower = ep.outputHint?.toLowerCase() ?? "";
+  const responseBlob = [ep.response?.itemsPath, ep.response?.totalPath, ep.pagination?.mode].filter((s) => typeof s === "string" && s.length > 0).join(" ").toLowerCase();
+  const inputKeys = [];
+  if (isObject(ep.inputSchema)) {
+    const props = ep.inputSchema.properties;
+    if (isObject(props)) {
+      for (const key of Object.keys(props)) inputKeys.push(key);
+    }
+  }
+  const inputKeysLower = inputKeys.map((k) => k.toLowerCase());
+  for (const t of tokens) {
+    if (pathLower.includes(t)) {
+      score += FIELD_WEIGHTS.path;
+      matched.add("path");
+    }
+    if (opts.pathOnly) continue;
+    if (t === methodLower) {
+      score += FIELD_WEIGHTS.method;
+      matched.add("method");
+    }
+    if (descriptionLower.includes(t)) {
+      score += FIELD_WEIGHTS.description;
+      matched.add("description");
+    }
+    if (inputKeysLower.some((k) => k.includes(t))) {
+      score += FIELD_WEIGHTS.inputKey;
+      matched.add("inputKey");
+    }
+    if (outputHintLower.length > 0 && outputHintLower.includes(t)) {
+      score += FIELD_WEIGHTS.outputHint;
+      matched.add("outputHint");
+    }
+    if (responseBlob.length > 0 && responseBlob.includes(t)) {
+      score += FIELD_WEIGHTS.response;
+      matched.add("response");
+    }
+  }
+  if (score === 0) return { score: 0, matched: [] };
+  return {
+    score,
+    matched: [...matched].sort(),
+    ...inputKeys.length > 0 ? { inputKeys } : {}
+  };
+}
+function searchService(svc, opts) {
+  const tokens = tokenize(opts.query);
+  const endpoints = svc.endpoints ?? [];
+  const scored = [];
+  for (const ep of endpoints) {
+    if (opts.method !== void 0 && ep.method !== opts.method) continue;
+    const r = scoreEndpointMatch(ep, tokens, { pathOnly: opts.pathOnly });
+    if (r.score === 0) continue;
+    scored.push({
+      ep,
+      score: r.score,
+      matched: r.matched,
+      ...r.inputKeys !== void 0 ? { inputKeys: r.inputKeys } : {}
+    });
+  }
+  scored.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    if (a.ep.method !== b.ep.method) {
+      return a.ep.method < b.ep.method ? -1 : 1;
+    }
+    if (a.ep.path !== b.ep.path) return a.ep.path < b.ep.path ? -1 : 1;
+    return 0;
+  });
+  const truncated = scored.length > opts.limit;
+  const slice = scored.slice(0, opts.limit);
+  return {
+    service: svc.name,
+    query: opts.query,
+    matches: slice.map((s) => ({
+      method: s.ep.method,
+      path: s.ep.path,
+      description: s.ep.description,
+      score: s.score,
+      matched: s.matched,
+      ...s.inputKeys !== void 0 && s.inputKeys.length > 0 ? { inputKeys: s.inputKeys } : {},
+      ...s.ep.outputHint !== void 0 ? { outputHint: s.ep.outputHint } : {}
+    })),
+    ...truncated ? { truncated: true } : {}
+  };
+}
 function hasDescribableEndpoints(svc) {
   return svc.endpoints !== void 0 && svc.endpoints.length > 0;
 }
@@ -9093,18 +9210,39 @@ function createDescribeServiceTool(opts) {
   const serviceNames = [...serviceMap.keys()];
   const cache = /* @__PURE__ */ new Map();
   const inputSchema19 = import_zod24.z.object({
-    service: import_zod24.z.enum(serviceNames)
+    service: import_zod24.z.enum(serviceNames),
+    /**
+     * Plan 054 — free-text query. When set with no `path`, returns
+     * the compact ranked-match shape. Must be a non-empty string.
+     */
+    query: import_zod24.z.string().min(1).optional(),
+    /**
+     * Plan 054 — narrow ranked matches to one HTTP verb. Also used
+     * by the exact-endpoint branch in combination with `path`.
+     */
+    method: import_zod24.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional(),
+    /**
+     * Plan 054 — paired with `method` returns full endpoint detail;
+     * paired without `method` runs a path-only ranked search.
+     */
+    path: import_zod24.z.string().min(1).optional(),
+    /**
+     * Plan 054 — defaults to 8, capped at 20. Only meaningful in
+     * search modes; ignored when fetching the full catalog or one
+     * exact endpoint.
+     */
+    limit: import_zod24.z.number().int().min(1).max(MAX_SEARCH_LIMIT).optional()
   });
-  const description = `Look up the endpoint catalog for one configured API service. Returns every endpoint's method, path, description, input schema, and (when declared) pagination + response-extraction metadata. Call this before invoking \`ApiCall\` when the service has lazy endpoints; for paginated list endpoints, prefer \`ApiCall\` with \`pagination.auto: true\` over manually issuing one call per page. Services: ${serviceNames.join(", ")}.`;
+  const description = `Look up endpoints on one configured API service.
+  1. Search: DescribeService({ service, query }) returns compact ranked matches with method, path, description, and a relevance score. Use this for broad services where only one endpoint slice is needed. Add { method } to filter.
+  2. Detail: DescribeService({ service, method, path }) returns full endpoint detail including inputSchema. Call this after a search has picked a candidate.
+  3. Execute: ApiCall(...) with the chosen method, path, and inputs.
+Legacy: DescribeService({ service }) returns the full endpoint catalog \u2014 expensive for large services and discouraged for new code. Services: ${serviceNames.join(", ")}.`;
   return defineTool({
     name: opts.toolName ?? "DescribeService",
     description,
     inputSchema: inputSchema19,
     execute: async (input) => {
-      const cached = cache.get(input.service);
-      if (cached !== void 0) {
-        return { content: JSON.stringify(cached), metadata: { cached: true } };
-      }
       const svc = serviceMap.get(input.service);
       if (!svc) {
         return {
@@ -9112,6 +9250,56 @@ function createDescribeServiceTool(opts) {
           isError: true
         };
       }
+      const limit = Math.min(input.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
+      if (input.method !== void 0 && input.path !== void 0) {
+        const ep = (svc.endpoints ?? []).find(
+          (e) => e.method === input.method && e.path === input.path
+        );
+        if (ep === void 0) {
+          return {
+            content: JSON.stringify({
+              code: "ENDPOINT_NOT_FOUND",
+              service: input.service,
+              method: input.method,
+              path: input.path,
+              message: `No endpoint ${input.method} ${input.path} on service "${input.service}". Call DescribeService with { service, query } to search the catalog.`
+            }),
+            isError: true
+          };
+        }
+        return {
+          content: JSON.stringify(describeEndpoint(ep)),
+          metadata: { mode: "detail" }
+        };
+      }
+      if (input.query !== void 0) {
+        const result = searchService(svc, {
+          query: input.query,
+          ...input.method !== void 0 ? { method: input.method } : {},
+          limit,
+          pathOnly: false
+        });
+        return {
+          content: JSON.stringify(result),
+          metadata: { mode: "search" }
+        };
+      }
+      if (input.path !== void 0) {
+        const result = searchService(svc, {
+          query: input.path,
+          ...input.method !== void 0 ? { method: input.method } : {},
+          limit,
+          pathOnly: true
+        });
+        return {
+          content: JSON.stringify(result),
+          metadata: { mode: "search" }
+        };
+      }
+      const cached = cache.get(input.service);
+      if (cached !== void 0) {
+        return { content: JSON.stringify(cached), metadata: { cached: true } };
+      }
       const payload = describe(svc);
       cache.set(input.service, payload);
       return { content: JSON.stringify(payload), metadata: { cached: false } };
@@ -9188,7 +9376,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "he",
   "she"
 ]);
-function tokenize(text2) {
+function tokenize2(text2) {
   if (typeof text2 !== "string" || text2.length === 0) return [];
   const seen = /* @__PURE__ */ new Set();
   for (const raw of text2.toLowerCase().split(/[\W_]+/)) {
@@ -9303,7 +9491,7 @@ function splitSections(content, relPath) {
       heading: "",
       slug: `${relPath}#`,
       depth: 0,
-      words: tokenize(leadInBody),
+      words: tokenize2(leadInBody),
       preview: makePreview(leadInBody),
       startLine: 1,
       endLine: leadInEndLine
@@ -9319,7 +9507,7 @@ function splitSections(content, relPath) {
       heading: h.heading,
       slug: `${relPath}#${slugify(h.heading)}`,
       depth: h.depth,
-      words: tokenize(body),
+      words: tokenize2(body),
       preview: makePreview(body),
       startLine,
       endLine
@@ -9436,7 +9624,7 @@ function createSearchKnowledgeTool(opts) {
     inputSchema: inputSchema17,
     execute: async ({ query, maxResults }) => {
       const limit = Math.min(maxResults ?? cap, cap);
-      const queryTokens = tokenize(query);
+      const queryTokens = tokenize2(query);
       if (queryTokens.length === 0) {
         return { content: "no searchable tokens in query", isError: false };
       }
@@ -9461,7 +9649,7 @@ function createSearchKnowledgeTool(opts) {
       }
       const externalHits = [];
       for (const link of externals) {
-        const score = scoreOverlap(tokenize(link.description), queryTokens);
+        const score = scoreOverlap(tokenize2(link.description), queryTokens);
         if (score > 0) externalHits.push({ link, score });
       }
       const all = [