sdl-mcp 0.11.2 → 0.11.4

package/README.md

@@ -368,6 +368,8 @@ The sandboxed runtime execution tool (`sdl.runtime.execute`) has its own governa
 
 `sdl.context` is SDL-MCP's task-shaped context engine. Give it a task type (`debug`, `review`, `implement`, `explain`), a description, and a budget — it selects the right Iris Gate rungs, collects evidence, and returns context tuned to the job. In Code Mode, `sdl.context` provides the same retrieval surface without dropping into `sdl.workflow`.
 
+Unscoped natural-language context calls use confidence-gated hybrid retrieval by default. Exact symbol mentions and explicit `focusPaths` / `focusSymbols` stay on the fast path; low-confidence lexical results can escalate to bounded FTS + vector retrieval. Set `options.semantic: true` to force hybrid retrieval, or `options.semantic: false` to keep lexical-only behavior for deterministic debugging.
+
 The feedback loop (`sdl.agent.feedback`) records which symbols were useful and which were missing, improving future slice quality.
 
 For portable exports such as tickets and PR descriptions, use the CLI `sdl-mcp summary` command. It generates token-bounded context briefings in markdown, JSON, or clipboard format for use outside MCP environments.
@@ -375,6 +377,7 @@ For portable exports such as tickets and PR descriptions, use the CLI `sdl-mcp s
 **Why it matters:**
 
 - Task-shaped context retrieval plans the **right Iris Gate path** within a token budget
+- Confidence-gated hybrid retrieval improves discovery without slowing known-target lookups
 - Feedback loop records what was useful/missing, improving future slice quality
 - Portable context summaries export findings for use outside MCP environments
 
@@ -474,7 +477,7 @@ flowchart LR
 
 ### CLI Tool Access — No MCP Server Required
 
-Access 35 SDL-MCP action aliases directly from the command line with `sdl-mcp tool`. No MCP server, transport, or SDK is required.
+Access SDL-MCP direct action aliases plus the low-risk `action.search` and `manual` metadata proxies from the command line with `sdl-mcp tool`. No MCP server, transport, or SDK is required.
 
 ```bash
 # Search for symbols
@@ -489,14 +492,18 @@ echo '{"repoId":"my-repo"}' | sdl-mcp tool symbol.search --query "auth"
 # Apply a single-file targeted write
 sdl-mcp tool file.write --repo-id my-repo --file-path config/app.json \
   --json-path server.port --json-value 8080
+
+# Discover and inspect metadata without opening the graph DB
+sdl-mcp tool action.search --query manual --summary-only
+sdl-mcp tool manual --actions action.search --format json
 ```
 
-Features include typed argument coercion (string, number, boolean, string[], json), budget flag merging, stdin JSON piping with CLI flag precedence, auto-resolved `repoId` from cwd, four output formats (json, json-compact, pretty, table), typo suggestions, and per-action `--help`. The CLI dispatches through the same gateway router and Zod schemas as the MCP server — identical code paths, identical validation.
+Features include typed argument coercion (string, number, boolean, string[], json), budget flag merging, stdin JSON piping with CLI flag precedence, auto-resolved `repoId` from cwd for graph actions, four output formats (json, json-compact, pretty, table), typo suggestions, and per-action `--help`. Direct graph actions dispatch through the same gateway router and Zod schemas as the MCP server; `action.search` and `manual` run in process against the same metadata handlers used by MCP registration.
 
 **Why it matters:**
 
-- 35 direct action aliases accessible from **any terminal** — no server, transport, or SDK required
-- Same code paths and Zod validation as the MCP server — identical behavior
+- 36 direct graph/action aliases plus `action.search` and `manual` metadata proxies accessible from **any terminal** - no server, transport, or SDK required
+- Direct graph actions keep gateway-router/Zod parity; metadata proxies share the same MCP registration handlers
 - Four output formats (json, json-compact, pretty, table) for scripting and CI pipelines
 - Auto-resolves repoId from cwd, supports stdin JSON piping and per-action `--help`
 
@@ -506,12 +513,12 @@ Features include typed argument coercion (string, number, boolean, string[], jso
 
 ### Tool Gateway — Compact Tool Registration
 
-The tool gateway projects the 34 gateway-routable SDL actions into **4 namespace-scoped tools** (`sdl.query`, `sdl.code`, `sdl.repo`, `sdl.agent`), reducing `tools/list` overhead from the full flat schema surface to a compact gateway surface.
+The tool gateway projects the 35 gateway-routable SDL actions into **4 namespace-scoped tools** (`sdl.query`, `sdl.code`, `sdl.repo`, `sdl.agent`), reducing `tools/list` overhead from the full flat schema surface to a compact gateway surface.
 
 ```mermaid
 %%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
 flowchart LR
-    Before["Flat mode<br/>37 tools<br/>2 universal + 35 flat"] e1@--> After["Gateway mode<br/>6 tools<br/>2 universal + 4 gateway"]
+    Before["Flat mode<br/>38 tools<br/>2 universal + 36 flat"] e1@--> After["Gateway mode<br/>6 tools<br/>2 universal + 4 gateway"]
     After e2@--> Savings["Smaller tools/list payload<br/>lower agent startup overhead"]
 
     classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
@@ -529,7 +536,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 **Why it matters:**
 
 - Large reduction in `tools/list` overhead for gateway-first agents
-- 34 gateway-routable actions consolidated into 4 namespace-scoped tools for simpler agent selection
+- 35 gateway-routable actions consolidated into 4 namespace-scoped tools for simpler agent selection
 - Fewer tool choices means faster and more accurate tool dispatch by the agent
 - Choose Code Mode for task-shaped retrieval first; opt out of exclusive Code Mode when you also need regular flat or gateway tools
 
@@ -539,7 +546,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 
 ### Observability Dashboard
 
-Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP behaviour without parsing stderr logs. Cyberpunk-corporate dark UI at `/ui/observability` on the HTTP transport, plus REST + SSE APIs (`/api/observability/snapshot`, `/timeseries`, `/beam-explain`, `/stream`) for programmatic access. Surfaces cache hit rates, hybrid-retrieval breakdowns (FTS / vector / PPR / RRF), beam-search decision traces, indexing pipeline metrics, write-pool and drain saturation, packed-wire savings, SCIP ingest health, deterministic bottleneck classification, and OS-level resource samples. See [Observability Dashboard Deep Dive](./docs/feature-deep-dives/observability-dashboard.md).
+Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP behaviour without parsing stderr logs. GlitterKill dark UI at `/ui/observability` on the HTTP transport or the loopback-only `sdl-mcp serve --stdio --dashboard-port <port>` sidecar, plus REST + SSE APIs (`/api/observability/snapshot`, `/timeseries`, `/beam-explain`, `/stream`) for programmatic access. Surfaces cache hit rates, predictive-context outcome learning, hybrid-retrieval breakdowns (FTS / vector / PPR / RRF), beam-search decision traces, indexing pipeline metrics, write-pool and drain saturation, packed-wire token efficiency, and runtime CPU/memory/event-loop probes. See [Observability Dashboard Deep Dive](./docs/feature-deep-dives/observability-dashboard.md).
 
 <br/>
 
@@ -551,9 +558,9 @@ Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP be
 
 | Mode                | Tool count | Composition                                                      |
 | :------------------ | :--------- | :--------------------------------------------------------------- |
-| Flat                | `37`       | `2` universal + `35` flat tools                                  |
+| Flat                | `38`       | `2` universal + `36` flat tools                                  |
 | Gateway             | `6`        | `2` universal + `4` gateway tools                                |
-| Gateway + legacy    | `41`       | `2` universal + `4` gateway + `35` flat tools                    |
+| Gateway + legacy    | `42`       | `2` universal + `4` gateway + `36` flat tools                    |
 | Code Mode exclusive | `5`        | `sdl.action.search`, `sdl.context`, `sdl.file`, `sdl.manual`, `sdl.workflow` |
 
 The generated source of truth is [`docs/generated/tool-inventory.md`](./docs/generated/tool-inventory.md).
@@ -571,9 +578,10 @@ The generated source of truth is [`docs/generated/tool-inventory.md`](./docs/gen
 <tr><td><code>sdl.buffer.checkpoint</code></td><td>Force-write pending buffers to the durable database</td></tr>
 <tr><td><code>sdl.buffer.status</code></td><td>Live indexing diagnostics and queue depth</td></tr>
 
-<tr><td rowspan="2"><strong>Symbols</strong></td>
+<tr><td rowspan="3"><strong>Symbols</strong></td>
     <td><code>sdl.symbol.search</code></td><td>Search symbols by name (with optional semantic reranking)</td></tr>
 <tr><td><code>sdl.symbol.getCard</code></td><td>Get one card or batch-fetch up to 100 cards with ETag-based conditional support</td></tr>
+<tr><td><code>sdl.symbol.edit</code></td><td>Preview/apply one symbol-scoped edit with AST, range, file, and draft preconditions</td></tr>
 
 <tr><td rowspan="3"><strong>Slices</strong></td>
     <td><code>sdl.slice.build</code></td><td>Build a task-scoped dependency subgraph</td></tr>
@@ -643,7 +651,7 @@ The generated source of truth is [`docs/generated/tool-inventory.md`](./docs/gen
 | `sdl-mcp doctor`    | Validate runtime, config, DB, grammars, repo access                                    |
 | `sdl-mcp index`     | Index repositories (with optional `--watch` mode)                                      |
 | `sdl-mcp serve`     | Start MCP server (`--stdio` or `--http`)                                               |
-| `sdl-mcp tool`      | Access 35 direct action aliases ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
+| `sdl-mcp tool`      | Access 36 direct action aliases ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
 | `sdl-mcp info`      | Runtime diagnostics — version, Node.js, platform, database, config                     |
 | `sdl-mcp summary`   | Generate copy/paste context summaries from the CLI                                     |
 | `sdl-mcp health`    | Compute composite health score with badge/JSON output                                  |
@@ -765,8 +773,8 @@ flowchart TD
 | [Context Modes](./docs/feature-deep-dives/context-modes.md)                         | Precise vs broad retrieval, adaptive symbol ranking, benchmark trade-offs             |
 | [Indexing & Languages](./docs/feature-deep-dives/indexing-languages.md)             | Rust/TS engines, two-pass architecture, 12-language support                           |
 | [Runtime Execution](./docs/feature-deep-dives/runtime-execution.md)                 | Sandboxed subprocess execution with governance                                        |
-| [CLI Tool Access](./docs/feature-deep-dives/cli-tool-access.md)                     | Direct CLI access to 35 action aliases, output formats, stdin piping, scripting       |
-| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md)                           | 34 gateway-routable actions, 4 namespace tools, thin schemas, migration guide         |
+| [CLI Tool Access](./docs/feature-deep-dives/cli-tool-access.md)                     | Direct CLI access to 36 action aliases, output formats, stdin piping, scripting       |
+| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md)                           | 35 gateway-routable actions, 4 namespace tools, thin schemas, migration guide         |
 | [Semantic Engine](./docs/feature-deep-dives/semantic-engine.md)                     | Pass-2 call resolution, embedding search, LLM summaries, confidence scoring           |
 | [Semantic Embeddings Setup](./docs/feature-deep-dives/semantic-embeddings-setup.md) | Dependencies, model installation, provider configuration, tier-by-tier setup          |
 | [Code Mode](./docs/feature-deep-dives/code-mode.md)                                 | `sdl.context`, `sdl.workflow`, action discovery, manual reference, one-call workflows |

package/config/sdlmcp.config.example.json

@@ -116,8 +116,13 @@
   "semantic": {
     "enabled": true,
     "provider": "local",
-    "model": "jina-embeddings-v2-base-code",
-    "additionalModels": ["nomic-embed-text-v1.5"],
+    "embeddingProfile": "specialized",
+    "symbolEmbeddingModels": [
+      "jina-embeddings-v2-base-code"
+    ],
+    "fileSummaryEmbeddingModels": [
+      "nomic-embed-text-v1.5"
+    ],
     "modelCacheDir": null,
     "generateSummaries": false,
     "summaryProvider": null,
@@ -132,7 +137,9 @@
     "fileSummaryEmbeddingMaxChars": 4096,
     "embeddingsSequential": false,
     "modelVariant": "default",
-    "executionProviders": ["cpu"],
+    "executionProviders": [
+      "cpu"
+    ],
     "retrieval": {
       "mode": "hybrid",
       "extensionsOptional": true,
@@ -187,7 +194,17 @@
   "prefetch": {
     "enabled": true,
     "maxBudgetPercent": 20,
-    "warmTopN": 0
+    "warmTopN": 0,
+    "policy": {
+      "enabled": true,
+      "mode": "safe",
+      "minSamples": 20,
+      "suppressionWasteRate": 0.8,
+      "boostHitRate": 0.35,
+      "retentionDays": 14,
+      "maxPriorityBoost": 25,
+      "maxBudgetTrimPercent": 50
+    }
   },
   "tracing": {
     "enabled": true,
@@ -223,7 +240,12 @@
   },
   "runtime": {
     "enabled": true,
-    "allowedRuntimes": ["node", "typescript", "python", "shell"],
+    "allowedRuntimes": [
+      "node",
+      "typescript",
+      "python",
+      "shell"
+    ],
     "allowedExecutables": [],
     "maxDurationMs": 30000,
     "maxStdoutBytes": 1048576,
@@ -290,5 +312,10 @@
   },
   "memory": {
     "enabled": false
+  },
+  "$": {
+    "prefetch": {
+      "policy": "{\"enabled\":true,\"mode\":\"safe\",\"minSamples\":20,\"suppressionWasteRate\":0.8,\"boostHitRate\":0.35,\"retentionDays\":14,\"maxPriorityBoost\":25,\"maxBudgetTrimPercent\":50}"
+    }
   }
 }

package/config/sdlmcp.config.json

@@ -145,8 +145,9 @@
     "provider": "mock",
     "executionProviders": ["cpu"],
     "modelVariant": "default",
-    "model": "jina-embeddings-v2-base-code",
-    "additionalModels": ["nomic-embed-text-v1.5"],
+    "embeddingProfile": "specialized",
+    "symbolEmbeddingModels": ["jina-embeddings-v2-base-code"],
+    "fileSummaryEmbeddingModels": ["nomic-embed-text-v1.5"],
     "generateSummaries": false
   },
   "prefetch": {

package/config/sdlmcp.config.schema.json

@@ -552,20 +552,36 @@
           "enum": ["api", "local", "mock"],
           "default": "local"
         },
+        "embeddingProfile": {
+          "type": "string",
+          "enum": ["specialized", "max-recall"],
+          "default": "specialized",
+          "description": "Semantic embedding model profile. 'specialized' embeds Symbols with Jina and FileSummary nodes with Nomic. 'max-recall' restores both supported models on both lanes."
+        },
+        "symbolEmbeddingModels": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["jina-embeddings-v2-base-code"],
+          "description": "Embedding models to populate for Symbol nodes. Overrides embeddingProfile for the Symbol lane when set."
+        },
+        "fileSummaryEmbeddingModels": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["nomic-embed-text-v1.5"],
+          "description": "Embedding models to populate for FileSummary nodes. Overrides embeddingProfile for the FileSummary lane when set."
+        },
         "model": {
           "type": "string",
-          "enum": ["jina-embeddings-v2-base-code", "nomic-embed-text-v1.5"],
-          "default": "jina-embeddings-v2-base-code"
+          "description": "Deprecated legacy primary embedding model. When no embeddingProfile or per-lane model arrays are configured, model plus additionalModels are treated as one shared model list for both Symbol and FileSummary embeddings."
         },
         "additionalModels": {
           "type": "array",
           "items": { "type": "string" },
-          "default": ["nomic-embed-text-v1.5"],
-          "description": "Extra embedding models to populate at index time so multiple vector lanes can contribute to hybrid fusion. Primary `model` is always populated; each name listed here gets a separate pass. Unknown model names are skipped."
+          "description": "Deprecated legacy shared extra embedding models. Use embeddingProfile, symbolEmbeddingModels, or fileSummaryEmbeddingModels instead."
         },
         "modelCacheDir": {
           "type": "string",
-          "description": "Override directory for downloaded model files (nomic-embed-text-v1.5). Defaults to platform-specific cache."
+          "description": "Override directory for downloaded local embedding model files. Defaults to the platform-specific SDL-MCP model cache."
         },
         "generateSummaries": {
           "type": "boolean",
@@ -830,7 +846,9 @@
       "default": {
         "enabled": true,
         "provider": "local",
-        "model": "jina-embeddings-v2-base-code",
+        "embeddingProfile": "specialized",
+        "symbolEmbeddingModels": ["jina-embeddings-v2-base-code"],
+        "fileSummaryEmbeddingModels": ["nomic-embed-text-v1.5"],
         "generateSummaries": false,
         "summaryModel": "claude-haiku-4-5-20251001",
         "summaryMaxConcurrency": 5,
@@ -996,12 +1014,47 @@
           "minimum": 0,
           "default": 0,
           "description": "Number of top-fan-in symbols to prefetch on serve start. Default 0 disables startup warming; raise only when you have evidence the warm set is consumed within the 5-minute stale window."
+        },
+        "policy": {
+          "type": "object",
+          "description": "Outcome-trained predictive context policy. Safe mode can suppress, trim, or boost existing prefetch strategies but cannot invent new strategy types.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "mode": { "enum": ["observe", "safe"], "default": "safe" },
+            "minSamples": { "type": "integer", "minimum": 1, "default": 20 },
+            "suppressionWasteRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.8 },
+            "boostHitRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.35 },
+            "retentionDays": { "type": "integer", "minimum": 1, "default": 14 },
+            "maxPriorityBoost": { "type": "integer", "minimum": 0, "maximum": 100, "default": 25 },
+            "maxBudgetTrimPercent": { "type": "integer", "minimum": 0, "maximum": 100, "default": 50 }
+          },
+          "default": {
+            "enabled": true,
+            "mode": "safe",
+            "minSamples": 20,
+            "suppressionWasteRate": 0.8,
+            "boostHitRate": 0.35,
+            "retentionDays": 14,
+            "maxPriorityBoost": 25,
+            "maxBudgetTrimPercent": 50
+          }
         }
       },
       "default": {
         "enabled": true,
         "maxBudgetPercent": 20,
-        "warmTopN": 0
+        "warmTopN": 0,
+        "policy": {
+          "enabled": true,
+          "mode": "safe",
+          "minSamples": 20,
+          "suppressionWasteRate": 0.8,
+          "boostHitRate": 0.35,
+          "retentionDays": 14,
+          "maxPriorityBoost": 25,
+          "maxBudgetTrimPercent": 50
+        }
       }
     },
     "observability": {
@@ -1193,7 +1246,7 @@
         },
         "toolQueueTimeoutMs": {
           "type": "integer",
-          "description": "Timeout for queued tool dispatch operations in milliseconds",
+          "description": "How long a foreground MCP tool request can wait for a dispatch slot before its handler starts. Timed-out requests fail with a retryable unavailable error; running handlers are not canceled.",
           "minimum": 5000,
           "maximum": 120000,
           "default": 30000