pi-context-engine 0.1.0 → 0.1.2

package/README.md

@@ -58,6 +58,20 @@ Ten tools the agent can call, plus three slash commands.
 
 Commands: `/context-index [--full]`, `/context-status`, `/context-savings`.
 
+**Shipped guidance.** The package also injects a ~900-token guidance section
+into the system prompt while `context_search` is active: how to formulate
+queries, when *not* to search, how to read confidence and overflow markers,
+and the index lifecycle.
+
+- **Why it ships:** retrieval only saves tokens when queries are good, and
+  these rules describe this package's own semantics. Keeping them in the tool
+  description alone would leave every user guessing.
+- **Cost-aware gate:** the section appears only while the tool is selected, and
+  `guidance.enabled: false` turns it off entirely for prompt-lean setups.
+- **Structured, not forced:** it is written to `systemPromptOptions.sections`,
+  so pi replays and diffs it like any other section instead of freezing the
+  whole prompt.
+
 ## How it works
 
 1. **Chunk**: tree-sitter parses source into functions, classes and modules.
@@ -93,6 +107,8 @@ retrieval:
   top_k: 20
   confidence_threshold: 0.2
   marginal_ratio: 0.75   # stop adding chunks below this fraction of the top score
+guidance:
+  enabled: true          # inject context_search guidance into the system prompt
 compression:
   level: standard        # minimal | standard | full
   ollama_url: http://localhost:11434

package/docs/ARCHITECTURE.md

@@ -26,6 +26,7 @@ pi session
 | `indexer/embedder.ts` | Ollama + local ONNX backends, selection | `indexer/embedder.py` |
 | `indexer/secrets.ts` | Secret filename skip, content redaction, PII scrub | `indexer/secrets.py` |
 | `retrieval/retriever.ts` | RRF merge, confidence blend, graph expansion | `retrieval/retriever.py` |
+| `guidance.ts` | Query-formulation system-prompt section (config-gated) | upstream's session-start tool instructions |
 | `compression/compressor.ts` | Truncation signatures, Ollama summaries, quality gate | `compression/*` |
 | `memory/db.ts` | Schema, vec recall, savings ledger, retention | `memory/db.py` |
 | `memory/grammar.ts` | Deterministic prose compression | `memory/grammar.py` |
@@ -71,6 +72,11 @@ contending with embedding writes. Upstream made the same split.
 - **Best-effort everywhere it must not crash.** Savings accounting, audit logs,
   session capture and shutdown all swallow their own errors: an instrumentation
   problem must never break a tool response.
+- **Guidance pays for its tokens or does not ship.** The ~900-token section is
+  injected only when `context_search` is in the run's selected tools *and*
+  `guidance.enabled` is true, through `sections` (replayable, diffable) rather
+  than a forced prompt replacement. Users who count prompt tokens opt out with
+  one config line.
 
 ## Degradation paths
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-context-engine",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "Semantic code context for pi: tree-sitter index + hybrid vector/BM25 retrieval + cross-session memory, all local. Port of code-context-engine (MIT, elara-labs) as a native pi extension.",
 	"keywords": [
 		"pi-package",
@@ -29,7 +29,8 @@
 		"check": "npm run typecheck && npm run test",
 		"smoke:env": "node scripts/smoke-env.mjs",
 		"smoke:loader": "node scripts/smoke-loader.mjs",
-		"smoke:real-world": "tsx scripts/smoke-real-world.mjs"
+		"smoke:real-world": "tsx scripts/smoke-real-world.mjs",
+		"prepublishOnly": "node -e \"if(!process.env.CI)throw new Error('publish via release.yml CI: push a v* tag. Manual npm publish is blocked to guarantee provenance + version sync.')\""
 	},
 	"pi": {
 		"extensions": [

package/src/config.ts

@@ -51,6 +51,12 @@ export interface Config {
 	ollamaUrl: string;
 	embeddingModel: string;
 	ollamaEmbedModel: string;
+	/**
+	 * Inject the query-formulation guidance section into the system prompt
+	 * while `context_search` is active. Default true: retrieval quality depends
+	 * on how queries are written. Set false for the leanest possible prompt.
+	 */
+	guidanceEnabled: boolean;
 	retrievalConfidenceThreshold: number;
 	retrievalTopK: number;
 	retrievalMarginalRatio: number;
@@ -74,6 +80,7 @@ export function defaultConfig(): Config {
 		ollamaUrl: "http://localhost:11434",
 		embeddingModel: "local",
 		ollamaEmbedModel: "nomic-embed-text",
+		guidanceEnabled: true,
 		retrievalConfidenceThreshold: 0.2,
 		retrievalTopK: 20,
 		retrievalMarginalRatio: 0.75,
@@ -96,6 +103,7 @@ const MAPPING: Record<string, keyof Config> = {
 	"compression.level": "compressionLevel",
 	"compression.model": "compressionModel",
 	"compression.ollama_url": "ollamaUrl",
+	"guidance.enabled": "guidanceEnabled",
 	"embedding.model": "embeddingModel",
 	"embedding.ollama_model": "ollamaEmbedModel",
 	"retrieval.confidence_threshold": "retrievalConfidenceThreshold",

package/src/extension.ts

@@ -11,6 +11,7 @@ import { Type } from "typebox";
 import fs from "node:fs";
 import path from "node:path";
 import { ContextEngine, isPceConfig } from "./engine.js";
+import { applyContextSearchGuidance } from "./guidance.js";
 
 /** Tools whose payloads are worth capturing for session timelines. */
 const CAPTURED_TOOLS = new Set(["bash", "read", "edit", "write", "grep", "find", "ls"]);
@@ -305,6 +306,12 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 		promptNumber = eng.recordPrompt(event.prompt ?? "");
 		eng.enqueueTurnCompression(promptNumber);
 
+		// Query-formulation guidance for context_search: gated on the tool being
+		// active and on `guidance.enabled` (config), so prompt-lean setups pay
+		// nothing. Section, not a forced prompt override: pi diffs it like any
+		// other section and the transcript stays stable.
+		applyContextSearchGuidance(event.systemPromptOptions, eng.config.guidanceEnabled);
+
 		// First prompt of the session: inject a compact "where you left off"
 		// block as a non-displayed custom message (upstream's SessionStart hook).
 		if (!bootstrapSent) {

package/src/guidance.ts

@@ -0,0 +1,114 @@
+/**
+ * System-prompt guidance for the package's own tools.
+ *
+ * Why this ships with the package: retrieval quality depends on how the query
+ * is written, and the tool's `promptSnippet`/`promptGuidelines` only say "use
+ * this instead of grep/read". Everything specific to *this* package's
+ * semantics (confidence scores, overflow references, `/context-index`, the
+ * empty-index background build) has to travel with the package, or it drifts
+ * the moment a tool parameter changes.
+ *
+ * Injection is gated on three conditions so the ~900-token block never lands
+ * where it does not pay for itself:
+ *  1. `context_search` must be in the run's selected tools
+ *  2. `guidance.enabled` must be true in config (default true)
+ *  3. only runs that start from a user prompt get the bootstrap message;
+ *     guidance itself applies to every run while the tool is active
+ *
+ * Registered through `systemPromptOptions.sections` rather than a forced
+ * `systemPrompt`: pi replays and diffs structured sections like any other, so
+ * the transcript stays stable instead of freezing a whole-prompt override.
+ */
+
+export const CONTEXT_SEARCH_SECTION_KEY = "context_search_guidelines";
+
+/** Minimal shape of the mutable prompt options this module touches. */
+export interface GuidanceTarget {
+	selectedTools: string[];
+	sections: Record<string, string>;
+}
+
+export const CONTEXT_SEARCH_GUIDELINES = `You have context_search, a semantic code search over this project's index (tree-sitter chunks, hybrid vector + BM25, confidence-scored). Use it well.
+
+### When to search vs. when not to
+
+SEARCH when:
+- Starting a new task and you need to understand the relevant code area
+- You need to find where a concept, pattern, or feature is implemented
+- Before editing code you haven't recently read
+- You need cross-file relationships (callers, imports, dependents)
+
+SKIP the search when:
+- You already have the file contents in context from a recent read
+- You were given an exact file path and line numbers
+- You need a simple exact-string match (use bash with grep/rg instead)
+- You are editing a file you just read in the current turn
+
+### Writing effective queries
+
+GOOD queries - specific, scoped, with concrete symbols or behaviour:
+- "How does the AuthenticationMiddleware validate JWT tokens? Show the verify method and its error handling"
+- "Where is the UserService.createUser method defined? Show the full implementation and parameters"
+- "Find all HTTP route handlers that accept file uploads"
+- "How does the EventBus dispatch events to subscribers?"
+
+POOR queries - vague, broad, or just a symbol dump:
+- "Show me the codebase"
+- "Authentication"
+- "Find UserService"
+
+RULES:
+1. Describe WHAT you want in natural language - the index is semantic, prose works better than keywords
+2. Include CONTEXT: what it is for (implementation? debugging? refactoring?)
+3. Ask for the LEVEL OF DETAIL: "full method", "the interface and its implementors", "the call chain"
+4. Combine related lookups into ONE query instead of several calls
+
+### Reading the results
+
+- Each hit is a compressed chunk: \`[path:start] (confidence: 0.xx)\` followed by the code
+- A "\`expand_chunk\`" reference list means results were cut by the token budget - expand only the ones you actually need, never every entry
+- Confidence below ~0.5 usually means the index has nothing better; rephrase rather than trusting a weak hit
+- Results come from the index, not the live file: before editing, open the file with \`read\` to see its current state
+
+### Before editing code
+
+Search once with a query covering ALL of:
+- The function/method/class you are modifying (full implementation)
+- Its types and constants
+- Callers that could break
+
+Example: "I need to add a retry parameter to HttpClient.request. Show the HttpClient class with the request method, HttpClientConfig, every caller of request(), and error types it throws."
+
+### Iterative search
+
+If the first search misses:
+1. REPHRASE - the codebase may use different names than you expect
+2. BROADEN - add surroundings ("and the module that defines it")
+3. NARROW - add specifics ("the async version returning a Promise")
+4. Change ANGLE - search for tests, the type definition, or a usage example
+
+### Combining with other tools
+
+- \`related_context\` - walk import/defines edges from a hit to reach neighbouring code
+- \`read\` - full current file contents when you are about to edit (search returns excerpts)
+- \`bash\` with grep/rg - exact strings (TODO markers, error messages, literal identifiers)
+- \`bash\` with git - history: \`git log -p -- path/to/file\`
+
+### Index lifecycle
+
+- If a search says the index is empty, a background index is already running - retry shortly, or run \`/context-index\` for a synchronous build
+- After large refactors, \`reindex\` (or \`/context-index\`) keeps results current; \`index_status\` reports freshness and measured token savings
+- Incremental re-index only re-reads changed files, so it is cheap
+`;
+
+/**
+ * Apply the guidance section to mutable prompt options.
+ * No-op (and safe to call on every run) when the tool is inactive or the
+ * user turned guidance off. Returns whether it injected, for tests.
+ */
+export function applyContextSearchGuidance(options: GuidanceTarget, enabled: boolean): boolean {
+	if (!enabled) return false;
+	if (!options.selectedTools.includes("context_search")) return false;
+	options.sections[CONTEXT_SEARCH_SECTION_KEY] = CONTEXT_SEARCH_GUIDELINES;
+	return true;
+}