docdex 0.2.43 → 0.2.45

package/CHANGELOG.md

@@ -1,8 +1,11 @@
 # Changelog
 
-## 0.2.43
+## 0.2.45
+- Update packaged agent docs with FD-hardening guidance and bump release metadata to 0.2.45.
+
+## 0.2.44
 - Fix MCP tool schema compatibility with Claude Code by removing top-level anyOf from `docdex_dag_export`.
-- Bump release metadata to 0.2.43.
+- Bump release metadata to 0.2.44.
 
 ## 0.2.42
 - Bump release metadata to 0.2.42.

package/README.md

@@ -231,8 +231,9 @@ DOCDEX_OLLAMA_BASE_URL=http://127.0.0.1:11434 docdexd daemon --host 127.0.0.1 --
 Docdex runs as a local daemon serving:
 
 * **CLI Commands:** `docdexd chat`
-* **HTTP API:** `/search`, `/v1/ast`, `/v1/graph/impact`
+* **HTTP API:** `/search`, `/v1/capabilities`, `/v1/search/rerank`, `/v1/search/batch`, `/v1/ast`, `/v1/graph/impact`
 * **MCP Endpoints:** `/v1/mcp` and `/v1/mcp/sse`
+* **Capability Negotiation Tools:** `docdex_capabilities`, `docdex_rerank`, `docdex_batch_search`
 
 ### Multi-Repo Setup
 

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.43 ----
+---- START OF DOCDEX INFO V0.2.45 ----
 Docdex URL: http://127.0.0.1:28491
 Use this base URL for Docdex HTTP endpoints.
 Health check endpoint: `GET /healthz` (not `/v1/health`).
@@ -16,6 +16,7 @@ Health check endpoint: `GET /healthz` (not `/v1/health`).
 - When a Docdex feature makes a task easier/safer, you MUST use it instead of ad-hoc inspection. Examples: `docdex_search` for context, `docdex_open`/`/v1/snippet` for file slices, `docdex_symbols`/`docdex_ast` for structure, `docdex_impact_graph`/`docdex_impact_diagnostics` for dependency safety, and `docdex_dag_export` to review session traces.
 - For dependency/library docs, run `docdexd libs discover`/`docdexd libs fetch` and search with `include_libs` rather than web searching.
 - For test execution, use `docdexd run-tests` (or `docdexd test run-node`) instead of ad-hoc commands when feasible.
+- For daemon stability triage, prioritize FD hardening checks: startup nofile warning threshold (`DOCDEX_MIN_NOFILE_SOFT`), profile lock retry knobs (`DOCDEX_PROFILE_LOCK_MAX_ATTEMPTS`, `DOCDEX_PROFILE_LOCK_RETRY_BASE_MS`), installer pressure defaults (`DOCDEX_REPO_IDLE_SECONDS`, `DOCDEX_REPO_HIBERNATE_SECONDS`, `DOCDEX_REPO_CLEANUP_INTERVAL_SECONDS`), and `docs/ops/fd_exhaustion_playbook.md`.
 - For staged-change validation, use `docdexd hook pre-commit`.
 - For MCP client registration, use `docdexd mcp add` (or `--all`) instead of editing configs by hand.
 
@@ -146,6 +147,10 @@ Use these to verify index coverage, repo binding, and to read precise file slice
 - docdex_impact_graph: Mandatory before code changes to review inbound/outbound deps (use MCP/IPC if shell networking is blocked).
 - docdex_dag_export: Export dependency graph to plan change order.
 - HTTP /v1/initialize: Mount/bind a repo for HTTP daemon mode. Request JSON uses rootUri/root_uri (NOT repo_root).
+- HTTP /v1/capabilities: Read optional retrieval feature flags and bounded limits before using optional flows.
+- HTTP /v1/search/rerank: Rerank a candidate hit set; use when capability negotiation says rerank is available.
+- HTTP /v1/search/batch: Execute bounded multi-query retrieval in one request.
+- MCP tools `docdex_capabilities`, `docdex_rerank`, `docdex_batch_search`: optional capability/flow surfaces for Codali integration.
 - HTTP /v1/snippet: Fetch exact line-safe snippets for a doc_id returned by search.
 - HTTP /v1/impact/diagnostics: Inspect unresolved/dynamic imports when impact graphs look incomplete.
 
@@ -222,6 +227,41 @@ Notes:
 - `skip_local_search=true` effectively forces web discovery (Tier 2).
 - If DOCDEX_WEB_ENABLED=1, web discovery can be slow; plan timeouts accordingly.
 
+### 3a) Capabilities (HTTP)
+
+`GET /v1/capabilities`
+
+Returns the optional-feature capability contract and current limit values for retrieval extensions.
+
+### 3b) Rerank (HTTP)
+
+`POST /v1/search/rerank`
+
+Required JSON fields:
+- `query` (string)
+- `candidates` (array of search hits)
+
+Common optional fields:
+- `limit`, `repo_id`
+
+Notes:
+- Candidate sets are deterministically truncated to the rerank limit exposed by `/v1/capabilities`.
+- Response includes `returned_count`, `input_count`, `limit`, and `truncated`.
+
+### 3c) Batch search (HTTP)
+
+`POST /v1/search/batch`
+
+Required JSON fields:
+- `queries` (array of query strings)
+
+Common optional fields:
+- `limit`, `include_libs`, `repo_id`
+
+Notes:
+- Query lists are deterministically truncated to the batch limit exposed by `/v1/capabilities`.
+- Response includes `query_count`, `effective_query_count`, `results`, and `truncated`.
+
 ### 4) Snippet (HTTP)
 
 `GET /snippet/:doc_id`
@@ -263,6 +303,9 @@ Notes:
 Do not guess fields; use these canonical shapes.
 
 - `docdex_search`: `{ project_root, query, limit?, diff?, repo_only?, force_web? }`
+- `docdex_capabilities`: `{ project_root? }`
+- `docdex_rerank`: `{ project_root?, query, candidates, limit? }`
+- `docdex_batch_search`: `{ project_root?, queries, limit?, include_libs? }`
 - `docdex_open`: `{ project_root, path, start_line?, end_line?, head?, clamp? }` (range must be valid unless clamp/head used)
 - `docdex_files`: `{ project_root, limit?, offset? }`
 - `docdex_stats`: `{ project_root }`

package/lib/postinstall_setup.js

@@ -36,6 +36,16 @@ const AGENTS_DOC_FILENAME = "agents.md";
 const DOCDEX_INFO_START_PREFIX = "---- START OF DOCDEX INFO V";
 const DOCDEX_INFO_END = "---- END OF DOCDEX INFO -----";
 const DOCDEX_INFO_END_LEGACY = "---- END OF DOCDEX INFO ----";
+const LAUNCHD_NOFILE_SOFT = "65536";
+const LAUNCHD_NOFILE_HARD = "200000";
+const DAEMON_ENV_DEFAULTS = Object.freeze([
+  ["DOCDEX_BROWSER_AUTO_INSTALL", "0"],
+  ["DOCDEX_REPO_IDLE_SECONDS", "300"],
+  ["DOCDEX_REPO_HIBERNATE_SECONDS", "1800"],
+  ["DOCDEX_REPO_CLEANUP_INTERVAL_SECONDS", "60"],
+  ["DOCDEX_WEB_MAX_CONCURRENT_BROWSER_FETCHES", "1"],
+  ["DOCDEX_WEB_MAX_CONCURRENT_LLM", "1"]
+]);
 
 function defaultConfigPath() {
   return path.join(os.homedir(), ".docdex", "config.toml");
@@ -2247,13 +2257,65 @@ function isTempPath(value, osModule = os) {
 }
 
 function buildDaemonEnvPairs() {
-  return [["DOCDEX_BROWSER_AUTO_INSTALL", "0"]];
+  return DAEMON_ENV_DEFAULTS.map(([key, value]) => [key, value]);
 }
 
 function buildDaemonEnv() {
   return Object.fromEntries(buildDaemonEnvPairs());
 }
 
+function buildLaunchAgentPlist({
+  programArgs,
+  envPairs,
+  workingDir,
+  logDir,
+  nofileSoft = LAUNCHD_NOFILE_SOFT,
+  nofileHard = LAUNCHD_NOFILE_HARD
+} = {}) {
+  const envVars = (envPairs || []).flatMap(([key, value]) => [
+    `    <key>${key}</key>\n`,
+    `    <string>${value}</string>\n`
+  ]);
+  const args = (programArgs || []).map((arg) => `    <string>${arg}</string>\n`).join("");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n` +
+    `<plist version="1.0">\n` +
+    `<dict>\n` +
+    `  <key>Label</key>\n` +
+    `  <string>com.docdex.daemon</string>\n` +
+    `  <key>EnvironmentVariables</key>\n` +
+    `  <dict>\n` +
+    envVars.join("") +
+    `  </dict>\n` +
+    `  <key>ProgramArguments</key>\n` +
+    `  <array>\n` +
+    args +
+    `  </array>\n` +
+    (workingDir
+      ? `  <key>WorkingDirectory</key>\n` + `  <string>${workingDir}</string>\n`
+      : "") +
+    `  <key>RunAtLoad</key>\n` +
+    `  <true/>\n` +
+    `  <key>KeepAlive</key>\n` +
+    `  <true/>\n` +
+    `  <key>SoftResourceLimits</key>\n` +
+    `  <dict>\n` +
+    `    <key>NumberOfFiles</key>\n` +
+    `    <integer>${nofileSoft}</integer>\n` +
+    `  </dict>\n` +
+    `  <key>HardResourceLimits</key>\n` +
+    `  <dict>\n` +
+    `    <key>NumberOfFiles</key>\n` +
+    `    <integer>${nofileHard}</integer>\n` +
+    `  </dict>\n` +
+    `  <key>StandardOutPath</key>\n` +
+    `  <string>${path.join(logDir, "daemon.out.log")}</string>\n` +
+    `  <key>StandardErrorPath</key>\n` +
+    `  <string>${path.join(logDir, "daemon.err.log")}</string>\n` +
+    `</dict>\n` +
+    `</plist>\n`;
+}
+
 function escapeCmdArg(value) {
   return `"${String(value).replace(/"/g, "\"\"")}"`;
 }
@@ -2323,37 +2385,12 @@ function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir, star
     const logDir = path.join(os.homedir(), ".docdex", "logs");
     fs.mkdirSync(logDir, { recursive: true });
     const programArgs = [binaryPath, ...args];
-    const envVars = envPairs.flatMap(([key, value]) => [
-      `    <key>${key}</key>\n`,
-      `    <string>${value}</string>\n`
-    ]);
-    const plist = `<?xml version="1.0" encoding="UTF-8"?>\n` +
-      `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n` +
-      `<plist version="1.0">\n` +
-      `<dict>\n` +
-      `  <key>Label</key>\n` +
-      `  <string>com.docdex.daemon</string>\n` +
-      `  <key>EnvironmentVariables</key>\n` +
-      `  <dict>\n` +
-      envVars.join("") +
-      `  </dict>\n` +
-      `  <key>ProgramArguments</key>\n` +
-      `  <array>\n` +
-      programArgs.map((arg) => `    <string>${arg}</string>\n`).join("") +
-      `  </array>\n` +
-      (workingDir
-        ? `  <key>WorkingDirectory</key>\n` + `  <string>${workingDir}</string>\n`
-        : "") +
-      `  <key>RunAtLoad</key>\n` +
-      `  <true/>\n` +
-      `  <key>KeepAlive</key>\n` +
-      `  <true/>\n` +
-      `  <key>StandardOutPath</key>\n` +
-      `  <string>${path.join(logDir, "daemon.out.log")}</string>\n` +
-      `  <key>StandardErrorPath</key>\n` +
-      `  <string>${path.join(logDir, "daemon.err.log")}</string>\n` +
-      `</dict>\n` +
-      `</plist>\n`;
+    const plist = buildLaunchAgentPlist({
+      programArgs,
+      envPairs,
+      workingDir,
+      logDir
+    });
     fs.mkdirSync(path.dirname(plistPath), { recursive: true });
     fs.writeFileSync(plistPath, plist);
     if (!startNow) return { ok: true };
@@ -2820,6 +2857,7 @@ module.exports = {
   launchSetupWizard,
   applyAgentInstructions,
   buildDaemonEnv,
+  buildLaunchAgentPlist,
   resolveDaemonPortState,
   normalizeVersion
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docdex",
-  "version": "0.2.43",
+  "version": "0.2.45",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {