@agentskit/doc-bridge 0.1.0-alpha.2 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.0-alpha.3
+
+Dogfood round-2 fixes (search ranking, full-text body, peers, federation soft-fail).
+
+### Fixes
+- **Search ranking:** exact id / basename boost; ownership preferred for routing questions; path dedupe
+- **Full-text search:** knowledge entries store `body` excerpt; descriptions prefer frontmatter `purpose` and complete sentences
+- **ask:** next command prefers ownership match over knowledge-only
+- **Text UX:** multi-line search/ask matches (`[type] id`, path, summary)
+- **Federation:** missing/404 remote `llms.txt` soft-skipped (no hard fail)
+- **Peers:** optional peer ranges widened (`@agentskit/core` `>=1.0`, adapters `>=0.12`) so Layer 0 install is not blocked
+- **humanDoc:** more aliases (`packages/id`, `reference/packages/id`, path suffixes)
+
 ## 0.1.0-alpha.2
 
 Dogfood-driven polish after ecosystem install on agentskit, agentskit-os, playbook, and registry.

package/README.md

@@ -121,7 +121,7 @@ Contract: [`docs/spec/config-v1.md`](docs/spec/config-v1.md) · CLI: [`docs/spec
 
 ## Status
 
-**v0.1.0-alpha.2** — Dogfood polish (pnpm-aware checks, corpus ownership inference, playbook gate preset, git prepare build). Layer 1 RAG/chat via optional peers.
+**v0.1.0-alpha.3** — Dogfood polish (pnpm-aware checks, corpus ownership inference, playbook gate preset, git prepare build). Layer 1 RAG/chat via optional peers.
 
 ```bash
 pnpm install && pnpm build && pnpm test

package/dist/cli/program.js

@@ -469,7 +469,7 @@ var firstHeading = (markdown) => {
   }
   return void 0;
 };
-var firstParagraph = (markdown) => {
+var firstParagraph = (markdown, maxLen = 400) => {
   const { body } = parseFrontmatter(markdown);
   const lines = body.split("\n");
   const buf = [];
@@ -481,11 +481,27 @@ var firstParagraph = (markdown) => {
     }
     if (t.startsWith("#")) continue;
     if (t.startsWith("---")) continue;
+    if (t.startsWith("```")) break;
+    if (t.startsWith("|") || t.startsWith("- [") || t.startsWith("* [")) {
+      if (buf.length) break;
+      continue;
+    }
     buf.push(t);
-    if (buf.join(" ").length > 40) break;
-  }
-  const text = buf.join(" ").trim();
-  return text || void 0;
+    if (buf.join(" ").length >= maxLen) break;
+  }
+  let text = buf.join(" ").replace(/\s+/g, " ").trim();
+  if (!text) return void 0;
+  if (text.length <= maxLen) return text;
+  const sliced = text.slice(0, maxLen);
+  const sentenceEnd = Math.max(sliced.lastIndexOf(". "), sliced.lastIndexOf("! "), sliced.lastIndexOf("? "));
+  if (sentenceEnd > maxLen * 0.4) return sliced.slice(0, sentenceEnd + 1).trim();
+  const wordEnd = sliced.lastIndexOf(" ");
+  return (wordEnd > 0 ? sliced.slice(0, wordEnd) : sliced).trim();
+};
+var extractSearchBody = (markdown, maxLen = 6e3) => {
+  const { body } = parseFrontmatter(markdown);
+  const text = body.replace(/```[\s\S]*?```/g, " ").replace(/!\[[^\]]*\]\([^)]+\)/g, " ").replace(/\[[^\]]*\]\([^)]+\)/g, " ").replace(/^#+\s+/gm, "").replace(/[|>*_`#]/g, " ").replace(/\s+/g, " ").trim();
+  return text.length > maxLen ? text.slice(0, maxLen) : text;
 };
 var slugFromPath = (relPath) => {
   const base = relPath.replace(/\.mdx?$/, "");
@@ -543,7 +559,9 @@ var scanAgentCorpus = (root, config) => {
     const { data: frontmatter } = parseFrontmatter(raw);
     const id = frontmatterString(frontmatter, "id") ?? frontmatterString(frontmatter, "package") ?? slugFromPath(relToCorpus);
     const title = firstHeading(raw) ?? id;
-    const description = firstParagraph(raw);
+    const purpose = frontmatterString(frontmatter, "purpose");
+    const description = purpose ?? firstParagraph(raw, 400);
+    const body = extractSearchBody(raw);
     return {
       id,
       type: "agent-doc",
@@ -552,7 +570,8 @@ var scanAgentCorpus = (root, config) => {
       absPath: abs,
       relPath,
       frontmatter,
-      ...description ? { description } : {}
+      ...description ? { description } : {},
+      ...body ? { body } : {}
     };
   });
 };
@@ -685,11 +704,19 @@ var resolveHumanDoc = (packageId, override, fmHuman, humanDocs = {}) => {
     packageId,
     packageId.replace(/^@[^/]+\//, ""),
     packageId.replace(/^os-/, ""),
-    packageId.replace(/-pattern$/, "")
+    packageId.replace(/-pattern$/, ""),
+    `packages/${packageId}`,
+    `reference/packages/${packageId}`,
+    `packages/${packageId}/index`
   ];
   for (const alias of aliases) {
     if (humanDocs[alias]) return humanDocs[alias];
   }
+  for (const [key, url] of Object.entries(humanDocs)) {
+    if (key === packageId || key.endsWith(`/${packageId}`) || key.endsWith(`/${packageId}/index`) || key.endsWith(`-${packageId}`)) {
+      return url;
+    }
+  }
   return void 0;
 };
 var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root = process.cwd()) => {
@@ -775,7 +802,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.1.0-alpha.2";
+var PACKAGE_VERSION = "0.1.0-alpha.3";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1252,19 +1279,58 @@ import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
 import { resolve as resolve3 } from "path";
 
 // src/query/search.ts
-var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2);
+var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9@/_-]+/).filter((t) => t.length >= 2);
+var PACKAGE_INTENT = /\b(package|module|pkg|edit|change|where|owns?|ownership|handoff|start)\b/i;
+var scoreHay = (tokens, hay, weight = 1) => {
+  let score = 0;
+  for (const token of tokens) {
+    if (!hay.includes(token)) continue;
+    score += token.length * weight;
+    if (new RegExp(`(?:^|[^a-z0-9])${token}(?:[^a-z0-9]|$)`).test(hay)) {
+      score += token.length;
+    }
+  }
+  return score;
+};
+var identityBoost = (id, path, tokens, term) => {
+  const idLower = id.toLowerCase();
+  const termLower = term.toLowerCase().trim();
+  const base = path.split("/").pop()?.replace(/\.mdx?$/i, "").toLowerCase() ?? "";
+  let boost = 0;
+  if (idLower === termLower || base === termLower) boost += 200;
+  if (tokens.length === 1 && (idLower === tokens[0] || base === tokens[0])) boost += 200;
+  for (const token of tokens) {
+    if (idLower === token) boost += 120;
+    else if (idLower.startsWith(`${token}-`) || idLower.endsWith(`-${token}`)) boost += 40;
+    else if (idLower.includes(token) && idLower.length <= token.length + 4) boost += 30;
+    if (base === token) boost += 100;
+  }
+  if (tokens.includes(idLower)) boost += Math.max(0, 40 - idLower.length);
+  return boost;
+};
+var preferOwnership = (term) => PACKAGE_INTENT.test(term) || /^(where|how).*(edit|change|package|module)/i.test(term);
 var searchIndex = (index, term, limit = 20) => {
   const tokens = tokenize(term);
   if (!tokens.length) return [];
-  const matches = [];
-  for (const entry of index.knowledge) {
-    const hay = `${entry.id} ${entry.title} ${entry.description ?? ""} ${entry.path}`.toLowerCase();
-    let score = 0;
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length;
+  const wantOwnership = preferOwnership(term);
+  const byPath = /* @__PURE__ */ new Map();
+  const consider = (match) => {
+    const key = match.path;
+    const existing = byPath.get(key);
+    if (!existing) {
+      byPath.set(key, match);
+      return;
     }
+    const prefer = match.score > existing.score || match.score === existing.score && match.type === "ownership" && existing.type !== "ownership" || wantOwnership && match.type === "ownership" && existing.type !== "ownership" && match.score >= existing.score - 20;
+    if (prefer) byPath.set(key, match);
+  };
+  for (const entry of index.knowledge) {
+    const body = entry.body ?? "";
+    const hay = `${entry.id} ${entry.title} ${entry.description ?? ""} ${entry.path} ${body}`.toLowerCase();
+    let score = scoreHay(tokens, hay, 1);
+    score += identityBoost(entry.id, entry.path, tokens, term);
     if (score > 0) {
-      matches.push({
+      consider({
         type: "knowledge",
         id: entry.id,
         path: entry.path,
@@ -1274,22 +1340,31 @@ var searchIndex = (index, term, limit = 20) => {
     }
   }
   for (const [id, owner] of Object.entries(index.lookup?.ownership ?? {})) {
-    const hay = `${id} ${owner.path} ${owner.purpose ?? ""} ${owner.group ?? ""}`.toLowerCase();
-    let score = 0;
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length * 2;
-    }
+    const path = owner.agentDoc ?? owner.path;
+    const hay = `${id} ${owner.path} ${owner.purpose ?? ""} ${owner.group ?? ""} ${owner.agentDoc ?? ""} ${owner.humanDoc ?? ""}`.toLowerCase();
+    let score = scoreHay(tokens, hay, 2);
+    score += identityBoost(id, path, tokens, term);
+    if (wantOwnership) score += 25;
+    score += 15;
     if (score > 0) {
-      matches.push({
+      consider({
         type: "ownership",
         id,
-        path: owner.agentDoc ?? owner.path,
+        path,
         ...owner.purpose ? { summary: owner.purpose } : {},
         score
       });
     }
   }
-  return matches.sort((a, b) => b.score - a.score).slice(0, limit);
+  return [...byPath.values()].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const aExact = tokens.includes(a.id.toLowerCase()) ? 1 : 0;
+    const bExact = tokens.includes(b.id.toLowerCase()) ? 1 : 0;
+    if (bExact !== aExact) return bExact - aExact;
+    if (a.type === "ownership" && b.type !== "ownership") return -1;
+    if (b.type === "ownership" && a.type !== "ownership") return 1;
+    return a.id.localeCompare(b.id);
+  }).slice(0, limit);
 };
 
 // src/retriever/doc-bridge-retriever.ts
@@ -1328,10 +1403,14 @@ var defaultFetchText = async (url) => {
   return res.text();
 };
 var sourceText = async (root, source, fetchText) => {
-  if (/^https?:\/\//.test(source)) return fetchText(source);
-  const path = resolve3(root, source);
-  if (!existsSync7(path)) throw new Error(`Federation source not found: ${source}`);
-  return readFileSync9(path, "utf8");
+  try {
+    if (/^https?:\/\//.test(source)) return await fetchText(source);
+    const path = resolve3(root, source);
+    if (!existsSync7(path)) return null;
+    return readFileSync9(path, "utf8");
+  } catch {
+    return null;
+  }
 };
 var sameOrigin = (base, target) => {
   if (!/^https?:\/\//.test(base) || !/^https?:\/\//.test(target)) return true;
@@ -1370,22 +1449,28 @@ var chunksFromMarkdown = (property, raw, sourceUrl) => {
 var loadFederatedChunks = async (root, config, options = {}) => {
   const fetchText = options.fetchText ?? defaultFetchText;
   const chunks = [];
+  const warnings = [];
   for (const source of config.federation?.sources ?? []) {
     if (source.includeInRetriever === false || !source.llmsTxt) continue;
     const llms = await sourceText(root, source.llmsTxt, fetchText);
+    if (!llms) {
+      warnings.push(`federation source skipped (unavailable): ${source.id} \u2192 ${source.llmsTxt}`);
+      continue;
+    }
     chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt));
     const links = parseLlmsTxtLinks(llms);
     for (const link of links) {
       const url = !/^https?:\/\//.test(link.url) && source.rawBaseUrl ? `${source.rawBaseUrl.replace(/\/$/, "")}/${link.url.replace(/^\//, "")}` : link.url;
       if (!/\.(md|txt)(?:$|\?)/.test(url)) continue;
       if (!sameOrigin(source.llmsTxt, url)) continue;
-      try {
-        const raw = await sourceText(root, url, fetchText);
-        chunks.push(...chunksFromMarkdown(source.id, raw, url));
-      } catch {
-      }
+      const raw = await sourceText(root, url, fetchText);
+      if (raw) chunks.push(...chunksFromMarkdown(source.id, raw, url));
     }
   }
+  if (warnings.length && process.stderr.isTTY) {
+    for (const w of warnings) process.stderr.write(`${w}
+`);
+  }
   return chunks;
 };
 var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
@@ -1485,7 +1570,9 @@ var KnowledgeEntrySchema = z3.object({
   type: z3.string().min(1).max(128),
   title: z3.string().min(1).max(256),
   path: z3.string().min(1).max(512),
-  description: z3.string().max(1024).optional(),
+  description: z3.string().max(2048).optional(),
+  /** Flattened body excerpt for full-text search (not for display). */
+  body: z3.string().max(8e3).optional(),
   links: z3.array(z3.string().min(1).max(512)).max(64).optional(),
   tags: z3.array(z3.string().min(1).max(64)).max(32).optional()
 }).strict();
@@ -2614,35 +2701,38 @@ var writeTextQuery = (payload) => {
     writeLines([
       `Search: ${String(data.term ?? "")}`,
       `Matches: ${String(data.count ?? matches.length)}`,
-      ...matches.map(
-        (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
-      )
+      ...matches.length ? matches.map(
+        (match) => formatSearchMatch(match)
+      ) : ["  (none)"]
     ]);
     return;
   }
   writeLines([textValue(result.data)]);
 };
+var formatSearchMatch = (match) => {
+  const summary = match.summary ? match.summary.replace(/\s+/g, " ").slice(0, 100) : "";
+  const score = typeof match.score === "number" ? ` score=${match.score}` : "";
+  return `  [${match.type}] ${match.id}${score}
+    ${match.path}${summary ? `
+    ${summary}` : ""}`;
+};
 var writeTextSearch = (term, matches) => {
   writeLines([
     `Search: ${term}`,
     `Matches: ${matches.length}`,
-    ...matches.map(
-      (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
-    )
+    ...matches.length ? matches.map(formatSearchMatch) : ["  (none)"]
   ]);
 };
 var writeAsk = (question, matches, index) => {
-  const best = matches[0];
-  const owner = matches.find((match) => match.type === "ownership" || index.lookup?.ownership?.[match.id]);
-  const bestQuery = owner ? `ak-docs query ownership ${owner.id} --agent` : "ak-docs list knowledge --text";
+  const owner = matches.find((match) => match.type === "ownership") ?? matches.find((match) => Boolean(index.lookup?.ownership?.[match.id]));
+  const best = owner ?? matches[0];
+  const bestQuery = best && (best.type === "ownership" || index.lookup?.ownership?.[best.id]) ? `ak-docs query ownership ${best.id} --agent` : "ak-docs list knowledge --text";
   writeLines([
     `Question: ${question}`,
     best ? `Best match: ${best.type} ${best.id} (${best.path})` : "Best match: none",
     "",
     "Matches:",
-    ...matches.length ? matches.slice(0, 5).map(
-      (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
-    ) : ["No local matches. Try: ak-docs search <term>"],
+    ...matches.length ? matches.slice(0, 5).map(formatSearchMatch) : ["  No local matches. Try: ak-docs search <term>"],
     "",
     "Next commands:",
     ...best ? [