docdex 0.2.53 → 0.2.55

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## 0.2.53
+## 0.2.55
+- Raise installer-managed Codex MCP `tool_timeout_sec` and `startup_timeout_sec` defaults to 300 seconds.
+- Update packaged Codex MCP examples to show the 300-second timeout settings.
+
+## 0.2.54
 - Add a per-project actual cost savings table to `docdexd delegation savings --all`.
 - Include optional per-project `projects` telemetry entries for `/v1/telemetry/delegation?all=true`, resolving persisted repo telemetry to canonical project paths with live mounted-repo fallback.
 

package/README.md

@@ -165,8 +165,10 @@ If you need to configure your client manually:
 **TOML (Codex):**
 
 ```toml
-[mcp_servers]
-docdex = { url = "http://127.0.0.1:28491/v1/mcp" }
+[mcp_servers.docdex]
+url = "http://127.0.0.1:28491/v1/mcp"
+tool_timeout_sec = 300
+startup_timeout_sec = 300
 
 ```
 

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.53 ----
+---- START OF DOCDEX INFO V0.2.55 ----
 Docdex URL: http://127.0.0.1:28491
 Use this base URL for Docdex HTTP endpoints.
 Health check endpoint: `GET /healthz` (not `/v1/health`).
@@ -92,14 +92,14 @@ Precision tools for structural analysis. Do not rely on text search for definiti
 
 ### D. Local Delegation (Cheap Models)
 
-Use local delegation for low-complexity, code-generation-oriented tasks to reduce paid-model usage.
+Use local delegation for low-complexity code-writing tasks and lightweight general questions to reduce paid-model usage.
 
 | MCP Tool / HTTP | Purpose |
 | --- | --- |
 | docdex_local_completion | Delegate small tasks to a local model with strict output formats. |
 | HTTP /v1/delegate | HTTP endpoint for delegated completions with structured responses. |
 
-Required fields: `task_type`, `instruction`, `context`. Optional: `max_tokens`, `timeout_ms`, `mode` (`draft_only` or `draft_then_refine`), `agent` (local agent id/slug or `model:<name>` to force an Ollama model; raw model names from `docdexd delegation agents` are also accepted).
+Required fields: `task_type`, `instruction`, `context`. Optional: `max_tokens`, `timeout_ms`, `mode` (`draft_only` or `draft_then_refine`), `agent` (local agent id/slug or `model:<name>` to force an Ollama model; raw model names from `docdexd delegation agents` are also accepted). Use `general_question` for lightweight Q&A and the existing code-oriented task types for code writing/editing.
 Expensive model library: `docs/expensive_models.json` (match by `agent_id`, `agent_slug`, `model`, or adapter type; case-insensitive).
 To choose a local target, run `docdexd delegation agents` (or `--json`) and prefer:
 - `code_writer` for scaffolding/boilerplate/docstrings.
@@ -144,7 +144,7 @@ Use these to verify index coverage, repo binding, and to read precise file slice
 - docdex_open: Read narrow file slices after targets are identified.
 - docdex_tree: Render a filtered folder tree (prefer this over `rg --files` / `find`).
 - docdex_impact_diagnostics: Scan dynamic imports when imports are unclear or failing.
-- docdex_local_completion: Delegate low-complexity codegen tasks (tests, docstrings, boilerplate, simple refactors).
+- docdex_local_completion: Delegate low-complexity local tasks such as codegen work or lightweight general questions.
 - docdex_ast: Use AST queries for precise structure (class/function definitions, call sites, imports).
 - docdex_symbols: Use symbols to confirm exact signatures/locations before edits.
 - docdex_impact_graph: Mandatory before code changes to review inbound/outbound deps (use MCP/IPC if shell networking is blocked).
@@ -325,7 +325,7 @@ Do not guess fields; use these canonical shapes.
 - `docdex_memory_recall`: `{ project_root, query, top_k? }`
 - `docdex_get_profile`: `{ agent_id }`
 - `docdex_save_preference`: `{ agent_id, category, content }`
-- `docdex_local_completion`: `{ task_type, instruction, context, max_tokens?, timeout_ms?, mode?, max_context_chars?, agent?, caller_agent_id?, caller_model?, primary_cost_per_million? }`
+- `docdex_local_completion`: `{ task_type, instruction, context, max_tokens?, timeout_ms?, mode?, max_context_chars?, agent?, caller_agent_id?, caller_model?, primary_cost_per_million?, project_root?, repo_path? }`
 - `docdex_web_research`: `{ project_root, query, force_web, skip_local_search?, web_limit?, no_cache? }`
 
 ### 9) Common error fixes (do not guess)
@@ -371,7 +371,7 @@ Use these when results look incomplete or when the task is about recent changes.
 
 ### 4. Local Delegation Workflow (Cheap Models)
 
-When you are an expensive/paid model, delegate eligible low-complexity tasks first unless the user opts out.
+When you are an expensive/paid model, delegate eligible low-complexity code-writing tasks and lightweight general questions first unless the user opts out.
 Delegation is mandatory for eligible tasks. If you are expensive and delegation is enabled (explicitly or auto-enabled with local candidates), you MUST attempt local delegation before doing the work yourself. Only skip when delegation is disabled, no local candidate exists, or local output fails validation after a retry/fallback.
 
 #### Mandatory Delegation Triggers
@@ -390,7 +390,7 @@ Delegation is mandatory for eligible tasks. If you are expensive and delegation
 
 1. Determine if you are expensive: load `docs/expensive_models.json` and match your `agent_id`, `agent_slug`, `model`, or adapter type. If you match, continue; if not and you are clearly local/cheap, skip delegation. If unsure, default to expensive.
 2. Check config: Only delegate when `[llm.delegation].enabled` is true or `auto_enable` is true with an eligible local model/agent (and `task_type` is allowed). For automatic mcoda selection, eligible means healthy and not paid/expensive unless the user explicitly overrides the target. If uncertain, attempt delegation and handle the error.
-3. Choose task type: Use one of `GENERATE_TESTS`, `WRITE_DOCSTRING`, `SCAFFOLD_BOILERPLATE`, `REFACTOR_SIMPLE`, `FORMAT_CODE`.
+3. Choose task type: Use one of `GENERATE_TESTS`, `WRITE_DOCSTRING`, `SCAFFOLD_BOILERPLATE`, `REFACTOR_SIMPLE`, `FORMAT_CODE`, `GENERAL_QUESTION`.
 4. Call the tool: `docdex_local_completion` with `task_type`, `instruction`, and minimal `context` (smallest necessary snippet).
 5. Validate output: If the local output is invalid or empty, fall back to the primary agent or handle with the paid model.
 6. Optional refine: If mode is `draft_then_refine`, refine the draft with the primary agent and return a final result.

package/lib/postinstall_setup.js

@@ -1145,6 +1145,7 @@ function upsertZedConfig(pathname, url) {
 }
 
 function upsertCodexConfig(pathname, url) {
+  const codexTimeoutSec = 300;
   const hasSection = (contents, section) =>
     new RegExp(`^\\s*\\[${section}\\]\\s*$`, "m").test(contents);
   const hasNestedMcpServers = (contents) =>
@@ -1213,13 +1214,20 @@ function upsertCodexConfig(pathname, url) {
   };
 
   const upsertDocdexNested = (contents, urlValue) => {
+    const desiredEntries = [
+      ["url", `"${urlValue}"`],
+      ["tool_timeout_sec", `${codexTimeoutSec}`],
+      ["startup_timeout_sec", `${codexTimeoutSec}`]
+    ];
     const lines = contents.split(/\r?\n/);
     const headerRe = /^\s*\[mcp_servers\.docdex\]\s*$/;
     let start = lines.findIndex((line) => headerRe.test(line));
     if (start === -1) {
       if (lines.length && lines[lines.length - 1].trim()) lines.push("");
       lines.push("[mcp_servers.docdex]");
-      lines.push(`url = "${urlValue}"`);
+      for (const [key, value] of desiredEntries) {
+        lines.push(`${key} = ${value}`);
+      }
       return { contents: lines.join("\n"), updated: true };
     }
     let end = start + 1;
@@ -1227,31 +1235,37 @@ function upsertCodexConfig(pathname, url) {
       end += 1;
     }
     let updated = false;
-    let urlIndex = -1;
-    for (let i = start + 1; i < end; i += 1) {
-      if (/^\s*url\s*=/.test(lines[i])) {
-        urlIndex = i;
-        break;
+    for (const [key, value] of desiredEntries) {
+      const lineValue = `${key} = ${value}`;
+      let keyIndex = -1;
+      for (let i = start + 1; i < end; i += 1) {
+        if (new RegExp(`^\\s*${key}\\s*=`).test(lines[i])) {
+          keyIndex = i;
+          break;
+        }
+      }
+      if (keyIndex === -1) {
+        lines.splice(end, 0, lineValue);
+        end += 1;
+        updated = true;
+      } else if (lines[keyIndex].trim() !== lineValue) {
+        lines[keyIndex] = lineValue;
+        updated = true;
       }
-    }
-    if (urlIndex === -1) {
-      lines.splice(start + 1, 0, `url = "${urlValue}"`);
-      updated = true;
-    } else if (!lines[urlIndex].includes(`"${urlValue}"`)) {
-      lines[urlIndex] = `url = "${urlValue}"`;
-      updated = true;
     }
     return { contents: lines.join("\n"), updated };
   };
 
   const upsertDocdexRoot = (contents, urlValue) => {
+    const entryLine =
+      `docdex = { url = "${urlValue}", tool_timeout_sec = ${codexTimeoutSec}, startup_timeout_sec = ${codexTimeoutSec} }`;
     const lines = contents.split(/\r?\n/);
     const headerRe = /^\s*\[mcp_servers\]\s*$/;
     const start = lines.findIndex((line) => headerRe.test(line));
     if (start === -1) {
       if (lines.length && lines[lines.length - 1].trim()) lines.push("");
       lines.push("[mcp_servers]");
-      lines.push(`docdex = { url = "${urlValue}" }`);
+      lines.push(entryLine);
       return { contents: lines.join("\n"), updated: true };
     }
     let end = start + 1;
@@ -1267,10 +1281,10 @@ function upsertCodexConfig(pathname, url) {
       }
     }
     if (docdexLine === -1) {
-      lines.splice(end, 0, `docdex = { url = "${urlValue}" }`);
+      lines.splice(end, 0, entryLine);
       updated = true;
-    } else if (!lines[docdexLine].includes(`"${urlValue}"`)) {
-      lines[docdexLine] = `docdex = { url = "${urlValue}" }`;
+    } else if (lines[docdexLine].trim() !== entryLine) {
+      lines[docdexLine] = entryLine;
       updated = true;
     }
     return { contents: lines.join("\n"), updated };

package/package.json

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