@pella-labs/pinakes 0.1.0

package/dist/mcp/envelope.d.ts

@@ -0,0 +1,73 @@
+/**
+ * MCP tool response envelope.
+ *
+ * CLAUDE.md §API Rules #5 — the envelope is immutable. Adding a field
+ * requires updating this file and regenerating the tool schemas. The LLM
+ * consumer parses this shape, so drift here breaks prompts in the wild.
+ */
+export type Scope = 'project' | 'personal' | 'both';
+export interface EnvelopeMeta {
+    /** User-requested `max_tokens` (default 5000, max 20000). */
+    tokens_budgeted: number;
+    /** Actual token count of the final serialized response body. */
+    tokens_used: number;
+    /** True if the budget gate truncated results or emitted a sentinel. */
+    results_truncated: boolean;
+    /** Scope this call ran against. */
+    scope: Scope;
+    /** Wall-clock time from tool entry to envelope build. */
+    query_time_ms: number;
+    /**
+     * Files whose on-disk `source_sha` no longer matches the indexed copy.
+     * Always empty in Phase 1 (in-memory store, no staleness concept).
+     * Phase 2+ populates this after the staleness check.
+     */
+    stale_files: string[];
+}
+/**
+ * The canonical response wrapper for both `kg_search` and `kg_execute`.
+ *
+ * `result` is the tool-specific payload. `meta` is always present and
+ * always has every field populated. `logs` is optional — present when the
+ * tool invoked `logger.log()` inside the sandbox, or when ingestion emitted
+ * warnings worth surfacing.
+ *
+ * Errors go inside `result` (e.g. `{ result: { error: "..." } }`) rather
+ * than being thrown or marked with `isError: true`, per CLAUDE.md
+ * §API Rules #8 — Claude Code has a bug where protocol-level errors display
+ * as "Error: undefined", and stuffing the error into the payload is the
+ * only way to keep it visible.
+ */
+export interface Envelope<T> {
+    result: T;
+    meta: EnvelopeMeta;
+    logs?: string[];
+}
+/**
+ * Build an envelope from its parts. Kept as a helper so the field order is
+ * stable (JSON stringification cares) and so the caller cannot forget a
+ * required meta field.
+ */
+export declare function buildEnvelope<T>(params: {
+    result: T;
+    tokensBudgeted: number;
+    tokensUsed: number;
+    resultsTruncated: boolean;
+    scope: Scope;
+    queryTimeMs: number;
+    staleFiles?: string[];
+    logs?: string[];
+}): Envelope<T>;
+/**
+ * Helper for measuring query wall-clock time. Captures a start timestamp
+ * on construction and returns the elapsed ms when `end()` is called. Using
+ * `performance.now()` instead of `Date.now()` for sub-ms resolution — the
+ * cold-start benchmark gate in Phase 1 tests #6 is measuring p50 at the
+ * 100ms scale, so millisecond precision matters.
+ */
+export declare class QueryTimer {
+    private readonly startMs;
+    constructor();
+    end(): number;
+}
+//# sourceMappingURL=envelope.d.ts.map

package/dist/mcp/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/mcp/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,mCAAmC;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,MAAM,EAAE,CAAC,CAAC;IACV,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE;IACvC,MAAM,EAAE,CAAC,CAAC;IACV,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAgBd;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;;IAMjC,GAAG,IAAI,MAAM;CAGd"}

package/dist/mcp/envelope.js

@@ -0,0 +1,46 @@
+/**
+ * MCP tool response envelope.
+ *
+ * CLAUDE.md §API Rules #5 — the envelope is immutable. Adding a field
+ * requires updating this file and regenerating the tool schemas. The LLM
+ * consumer parses this shape, so drift here breaks prompts in the wild.
+ */
+/**
+ * Build an envelope from its parts. Kept as a helper so the field order is
+ * stable (JSON stringification cares) and so the caller cannot forget a
+ * required meta field.
+ */
+export function buildEnvelope(params) {
+    const envelope = {
+        result: params.result,
+        meta: {
+            tokens_budgeted: params.tokensBudgeted,
+            tokens_used: params.tokensUsed,
+            results_truncated: params.resultsTruncated,
+            scope: params.scope,
+            query_time_ms: params.queryTimeMs,
+            stale_files: params.staleFiles ?? [],
+        },
+    };
+    if (params.logs && params.logs.length > 0) {
+        envelope.logs = params.logs;
+    }
+    return envelope;
+}
+/**
+ * Helper for measuring query wall-clock time. Captures a start timestamp
+ * on construction and returns the elapsed ms when `end()` is called. Using
+ * `performance.now()` instead of `Date.now()` for sub-ms resolution — the
+ * cold-start benchmark gate in Phase 1 tests #6 is measuring p50 at the
+ * 100ms scale, so millisecond precision matters.
+ */
+export class QueryTimer {
+    startMs;
+    constructor() {
+        this.startMs = performance.now();
+    }
+    end() {
+        return Math.round(performance.now() - this.startMs);
+    }
+}
+//# sourceMappingURL=envelope.js.map

package/dist/mcp/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/mcp/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2CH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAI,MAShC;IACC,MAAM,QAAQ,GAAgB;QAC5B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE;YACJ,eAAe,EAAE,MAAM,CAAC,cAAc;YACtC,WAAW,EAAE,MAAM,CAAC,UAAU;YAC9B,iBAAiB,EAAE,MAAM,CAAC,gBAAgB;YAC1C,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,aAAa,EAAE,MAAM,CAAC,WAAW;YACjC,WAAW,EAAE,MAAM,CAAC,UAAU,IAAI,EAAE;SACrC;KACF,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,QAAQ,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,UAAU;IACJ,OAAO,CAAS;IAEjC;QACE,IAAI,CAAC,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACnC,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IACtD,CAAC;CACF"}

package/dist/mcp/tools/execute.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import type { Repository } from '../../db/repository.js';
+import type { DbBundle } from '../../db/client.js';
+import type { QuickJSExecutor } from '../../sandbox/executor.js';
+import type { Embedder } from '../../retrieval/embedder.js';
+export declare const kgExecuteInputShape: {
+    code: z.ZodString;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        project: "project";
+        personal: "personal";
+        both: "both";
+    }>>;
+};
+export declare const kgExecuteToolConfig: {
+    readonly title: "Run JS in the knowledge-graph sandbox";
+    readonly description: string;
+    readonly inputSchema: {
+        code: z.ZodString;
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            project: "project";
+            personal: "personal";
+            both: "both";
+        }>>;
+    };
+};
+export interface KgExecuteDeps {
+    repository: Repository;
+    executor: QuickJSExecutor;
+    bundle: DbBundle;
+    embedder: Embedder;
+    wikiRoot?: string;
+    personalBundle?: DbBundle;
+    personalWikiRoot?: string;
+}
+/**
+ * Build the `kg_execute` handler. Phase 3 path: uses `executeWithBindings`
+ * with the full `kg.project.*` surface via the warm pool.
+ */
+export declare function makeKgExecuteHandler(deps: KgExecuteDeps): (args: {
+    code: string;
+    max_tokens?: number;
+    timeout_ms?: number;
+    scope?: "project" | "personal" | "both";
+}) => Promise<{
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    isError?: boolean;
+}>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/mcp/tools/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/execute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAmD5D,eAAO,MAAM,mBAAmB;;;;;;;;;CAuC/B,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;CAWtB,CAAC;AAEX,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,IACxC,MAAM;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;CACzC,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CA8F9E"}

package/dist/mcp/tools/execute.js

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { countEnvelopeTokens, countTokens, computeInternalBudget, fitResults } from '../../gate/budget.js';
+import { buildEnvelope, QueryTimer } from '../envelope.js';
+/**
+ * `kg_execute` — code-mode tool. The LLM writes a short JS snippet, we run
+ * it inside the QuickJS sandbox against the `kg` bindings, and return the
+ * (budget-shaped) result.
+ *
+ * Phase 3: full `kg.project.*` binding surface via warm pool. Backward-compat
+ * `kg.search()`/`kg.get()` aliases remain.
+ */
+const KG_EXECUTE_TYPES = `
+declare const kg: {
+  /** Substring search (backward compat). */
+  search(query: string): Array<{ id: string; text: string; source_uri: string }>;
+  /** Chunk lookup by id (backward compat). */
+  get(id: string): { id: string; text: string; source_uri: string } | null;
+  project: {
+    /** FTS5 full-text search with bm25 ranking. */
+    fts(query: string, opts?: { limit?: number }): Array<{ id: string; text: string; source_uri: string; node_id: string; rank: number; title: string | null; section_path: string }>;
+    /** Vector similarity search. Returns [] if no pre-computed embedding available. */
+    vec(query: string, opts?: { limit?: number }): Array<{ id: string; text: string; source_uri: string; node_id: string; distance: number; title: string | null; section_path: string }>;
+    /** Hybrid FTS + vector search with RRF fusion. Falls back to FTS-only if no embedding cached. */
+    hybrid(query: string, opts?: { limit?: number; rrf_k?: number }): Array<{ id: string; text: string; source_uri: string; node_id: string; score: number; snippet?: string; title: string | null; section_path: string }>;
+    /** Table of contents — list all nodes for LLM-driven browsing. Use this to scan titles, then get(id) to read specific sections. */
+    index(opts?: { kind?: string; source_uri?: string; limit?: number }): Array<{ id: string; title: string | null; source_uri: string; section_path: string; kind: string; token_count: number }>;
+    /** Node lookup by id — full section content. */
+    get(id: string): { id: string; source_uri: string; section_path: string; kind: string; title: string | null; content: string; token_count: number } | null;
+    /** K-hop graph traversal. */
+    neighbors(id: string, opts?: { depth?: number; edge_kinds?: string[] }): Array<{ id: string; source_uri: string; kind: string; title: string | null; depth: number }>;
+    log: {
+      /** Recent log entries. */
+      recent(n?: number, opts?: { kind?: string }): Array<{ id: number; ts: number; kind: string; source_uri: string | null; payload: unknown }>;
+    };
+    /** Concept gaps (stub, Phase 6). */
+    gaps(opts?: { resolved?: boolean; limit?: number }): never[];
+    /** Create or overwrite a wiki page. Path is relative to wiki root, .md extension enforced. */
+    write(path: string, content: string): { path: string; bytes: number };
+    /** Append a timestamped entry to log.md. */
+    append(entry: string): { path: string; bytes: number };
+    /** Delete a wiki page. Path is relative to wiki root. */
+    remove(path: string): { path: string; removed: true };
+  };
+};
+declare const budget: { fit(items: unknown[], maxTokens?: number): unknown[] };
+declare const logger: { log(...args: unknown[]): void };
+`.trim();
+export const kgExecuteInputShape = {
+    code: z
+        .string()
+        .min(1)
+        .describe('JavaScript to run inside the sandbox. The sandbox is QuickJS with ' +
+        '`eval`, `Function`, `fetch`, `require`, `process`, and `constructor` ' +
+        'removed. You have `kg.project.*` for FTS, graph traversal, log ' +
+        'queries, and wiki writes (write/append/remove), plus `budget.fit()` ' +
+        'for token-aware truncation and `logger.log()` captured into ' +
+        '`response.logs`. Return a value.\n' +
+        KG_EXECUTE_TYPES),
+    max_tokens: z
+        .number()
+        .int()
+        .positive()
+        .max(20_000)
+        .optional()
+        .describe('Maximum total tokens the response can contain. Default 5000, max 20000.'),
+    timeout_ms: z
+        .number()
+        .int()
+        .positive()
+        .max(10_000)
+        .optional()
+        .describe('Hard wall-clock execution timeout for the sandbox. Default 2000ms, ' +
+        'max 10000ms. If exceeded, the response contains an `error` string.'),
+    scope: z
+        .enum(['project', 'personal', 'both'])
+        .optional()
+        .describe('Which KG bindings to inject. "project" (default) installs kg.project, ' +
+        '"personal" installs kg.personal, "both" installs both namespaces.'),
+};
+export const kgExecuteToolConfig = {
+    title: 'Run JS in the knowledge-graph sandbox',
+    description: 'Run a short JavaScript snippet inside the KG sandbox. Use `kg.project.index()` ' +
+        'to browse the wiki table of contents, then `kg.project.get(id)` to read ' +
+        'specific sections. `kg.project.hybrid()` for search, ' +
+        '`kg.project.neighbors()` for graph traversal, `kg.project.log.recent()` for ' +
+        'event log. Legacy `kg.search()`/`kg.get()` also available. ' +
+        '64MB memory cap, 2s default timeout. No network, no eval.\n\n' +
+        KG_EXECUTE_TYPES,
+    inputSchema: kgExecuteInputShape,
+};
+/**
+ * Build the `kg_execute` handler. Phase 3 path: uses `executeWithBindings`
+ * with the full `kg.project.*` surface via the warm pool.
+ */
+export function makeKgExecuteHandler(deps) {
+    return async (args) => {
+        const timer = new QueryTimer();
+        const maxTokens = args.max_tokens ?? 5000;
+        const scope = args.scope ?? 'project';
+        // Check that personal scope is available if requested
+        if ((scope === 'personal' || scope === 'both') && !deps.personalBundle) {
+            const envelope = buildEnvelope({
+                result: {
+                    error: 'personal scope requested but no personal KG is configured — ' +
+                        'set KG_PROFILE_PATH or pass --profile-path',
+                },
+                tokensBudgeted: maxTokens,
+                tokensUsed: 0,
+                resultsTruncated: false,
+                scope,
+                queryTimeMs: timer.end(),
+            });
+            return wrapText(envelope);
+        }
+        const logs = [];
+        const writeCounter = { value: 0 };
+        // Build per-scope binding deps. Privacy invariant: only include
+        // the scope(s) the caller requested.
+        const bindingDeps = { maxTokens, logs };
+        if (scope === 'project' || scope === 'both') {
+            bindingDeps.project = {
+                repository: deps.repository,
+                bundle: deps.bundle,
+                scope: 'project',
+                embedder: deps.embedder,
+                wikiRoot: deps.wikiRoot,
+                writeCounter,
+            };
+        }
+        if ((scope === 'personal' || scope === 'both') && deps.personalBundle) {
+            bindingDeps.personal = {
+                repository: deps.repository,
+                bundle: deps.personalBundle,
+                scope: 'personal',
+                embedder: deps.embedder,
+                wikiRoot: deps.personalWikiRoot,
+                writeCounter,
+            };
+        }
+        const result = await deps.executor.executeWithBindings(args.code, bindingDeps, args.timeout_ms);
+        // Executor errors are in-payload per CLAUDE.md §API Rules #8.
+        if (result.error) {
+            const envelope = buildEnvelope({
+                result: { error: result.error },
+                tokensBudgeted: maxTokens,
+                tokensUsed: 0,
+                resultsTruncated: false,
+                scope,
+                queryTimeMs: timer.end(),
+                logs: result.logs,
+            });
+            const json = JSON.stringify(envelope);
+            envelope.meta.tokens_used = countEnvelopeTokens(json);
+            return wrapText(envelope);
+        }
+        // Apply the budget gate. If the result is an array, fitResults does
+        // the greedy truncation we want. If the result is a scalar or object,
+        // we check its total size and replace it with a truncation notice
+        // rather than emitting a too-large sentinel (which only makes sense
+        // for rank-ordered results).
+        const raw = result.result;
+        const { shapedResult, truncated, tokensUsed, tokensBudgeted } = shapeForBudget(raw, maxTokens);
+        const envelope = buildEnvelope({
+            result: shapedResult,
+            tokensBudgeted,
+            tokensUsed,
+            resultsTruncated: truncated,
+            scope,
+            queryTimeMs: timer.end(),
+            logs: result.logs,
+        });
+        const json = JSON.stringify(envelope);
+        envelope.meta.tokens_used = countEnvelopeTokens(json);
+        return wrapText(envelope);
+    };
+}
+/**
+ * Budget-shape the raw result of a sandbox execution. For array results
+ * we reuse `fitResults` with a synthetic id/uri extractor. For non-array
+ * results we measure the whole thing and replace it with a truncation
+ * notice if it overflows.
+ */
+function shapeForBudget(raw, maxTokens) {
+    const budget = computeInternalBudget(maxTokens);
+    if (Array.isArray(raw)) {
+        let arrayIdx = 0;
+        const fit = fitResults(raw, maxTokens, (item) => JSON.stringify(item), (item) => {
+            // Try to pull a stable id out of the item if it has one,
+            // otherwise fall back to an array-index pseudo-id.
+            const obj = item;
+            if (obj && typeof obj.id === 'string')
+                return obj.id;
+            return `[${arrayIdx++}]`;
+        }, (item) => {
+            const obj = item;
+            return obj && typeof obj.source_uri === 'string' ? obj.source_uri : '';
+        });
+        return {
+            shapedResult: fit.kept,
+            truncated: fit.truncated,
+            tokensUsed: fit.tokensUsed,
+            tokensBudgeted: fit.tokensBudgeted,
+        };
+    }
+    // Scalar, object, null, etc. — measure the whole thing.
+    const json = JSON.stringify(raw);
+    const cost = countTokens(json ?? 'null');
+    if (cost <= budget) {
+        return {
+            shapedResult: raw,
+            truncated: false,
+            tokensUsed: cost,
+            tokensBudgeted: budget,
+        };
+    }
+    // Too large for a scalar result. Replace with an error string so the
+    // LLM can retry with a higher max_tokens or re-query more narrowly.
+    return {
+        shapedResult: {
+            error: `result body is ${cost} tokens, which exceeds the internal budget ` +
+                `of ${budget} (max_tokens=${maxTokens}). Re-query with a higher ` +
+                `max_tokens or narrow your code to return fewer fields.`,
+        },
+        truncated: true,
+        tokensUsed: countTokens(JSON.stringify({ error: 'placeholder' })),
+        tokensBudgeted: budget,
+    };
+}
+function wrapText(envelope) {
+    return { content: [{ type: 'text', text: JSON.stringify(envelope) }] };
+}
+//# sourceMappingURL=execute.js.map

package/dist/mcp/tools/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../../src/mcp/tools/execute.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/search.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import type { Repository } from '../../db/repository.js';
+import type { DbBundle } from '../../db/client.js';
+import type { Embedder } from '../../retrieval/embedder.js';
+/**
+ * `kg_search` — fast-path hybrid search against the knowledge graph.
+ *
+ * Phase 5: supports all three scopes. For `scope='both'`, results from
+ * both KGs are merged and tagged with `source_scope`.
+ */
+export declare const kgSearchInputShape: {
+    query: z.ZodString;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        project: "project";
+        personal: "personal";
+        both: "both";
+    }>>;
+};
+export declare const kgSearchToolConfig: {
+    readonly title: "Search the knowledge graph";
+    readonly description: string;
+    readonly inputSchema: {
+        query: z.ZodString;
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            project: "project";
+            personal: "personal";
+            both: "both";
+        }>>;
+    };
+};
+export interface KgSearchDeps {
+    repository: Repository;
+    embedder: Embedder;
+    bundle: DbBundle;
+    personalBundle?: DbBundle;
+}
+/**
+ * Build the `kg_search` handler. Supports project, personal, and both scopes.
+ */
+export declare function makeKgSearchHandler(deps: KgSearchDeps): (args: {
+    query: string;
+    max_tokens?: number;
+    scope?: "project" | "personal" | "both";
+}) => Promise<{
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    isError?: boolean;
+}>;
+//# sourceMappingURL=search.d.ts.map

package/dist/mcp/tools/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAM5D;;;;;GAKG;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;CA6B9B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;CASrB,CAAC;AAEX,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,QAAQ,CAAC;IACjB,cAAc,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAaD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,IACtC,MAAM;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;CACzC,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CA4E9E"}

package/dist/mcp/tools/search.js

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { hybridSearch } from '../../retrieval/hybrid.js';
+import { fitResults, countEnvelopeTokens } from '../../gate/budget.js';
+import { buildEnvelope, QueryTimer } from '../envelope.js';
+import { nextReader } from '../../db/client.js';
+/**
+ * `kg_search` — fast-path hybrid search against the knowledge graph.
+ *
+ * Phase 5: supports all three scopes. For `scope='both'`, results from
+ * both KGs are merged and tagged with `source_scope`.
+ */
+export const kgSearchInputShape = {
+    query: z
+        .string()
+        .min(1)
+        .describe('The search term. Hybrid FTS5 + vector search against every indexed ' +
+        'chunk of the wiki, ranked by Reciprocal Rank Fusion. ' +
+        'Examples: "hashPassword", "bcrypt", "auth flow".'),
+    max_tokens: z
+        .number()
+        .int()
+        .positive()
+        .max(20_000)
+        .optional()
+        .describe('Maximum total tokens the response can contain. Defaults to 5000, max 20000. ' +
+        'The server applies a ~10% safety margin internally. If results would ' +
+        'exceed the budget, they are greedy-truncated in rank order and ' +
+        '`meta.results_truncated` is set to true.'),
+    scope: z
+        .enum(['project', 'personal', 'both'])
+        .optional()
+        .describe('Which KG to query. "project" (default) searches the project wiki, ' +
+        '"personal" searches the personal wiki, "both" merges results from ' +
+        'both with `source_scope` tagging on each result.'),
+};
+export const kgSearchToolConfig = {
+    title: 'Search the knowledge graph',
+    description: 'Hybrid FTS + vector search the knowledge graph and return matching ' +
+        'chunks ranked by Reciprocal Rank Fusion. Each result includes `title` ' +
+        'and `section_path` for quick triage without reading full content. ' +
+        'Prefer this for short lookups; use `kg_execute` when you need to chain ' +
+        'filters, browse the wiki index, or combine multiple queries in one call.',
+    inputSchema: kgSearchInputShape,
+};
+/**
+ * Build the `kg_search` handler. Supports project, personal, and both scopes.
+ */
+export function makeKgSearchHandler(deps) {
+    return async (args) => {
+        const timer = new QueryTimer();
+        const maxTokens = args.max_tokens ?? 5000;
+        const scope = args.scope ?? 'project';
+        // Check personal scope availability
+        if ((scope === 'personal' || scope === 'both') && !deps.personalBundle) {
+            const envelope = buildEnvelope({
+                result: {
+                    error: 'personal scope requested but no personal KG is configured — ' +
+                        'set KG_PROFILE_PATH or pass --profile-path',
+                },
+                tokensBudgeted: maxTokens,
+                tokensUsed: 0,
+                resultsTruncated: false,
+                scope,
+                queryTimeMs: timer.end(),
+            });
+            return wrapText(envelope);
+        }
+        let allHits = [];
+        if (scope === 'project' || scope === 'both') {
+            const reader = nextReader(deps.bundle);
+            const hits = await hybridSearch(reader, 'project', args.query, deps.embedder);
+            const tagged = hits.map((h) => ({
+                id: h.id, text: h.text, source_uri: h.source_uri, score: h.score,
+                confidence: h.confidence, title: h.title, section_path: h.section_path,
+                ...(scope === 'both' ? { source_scope: 'project' } : {}),
+            }));
+            allHits.push(...tagged);
+        }
+        if ((scope === 'personal' || scope === 'both') && deps.personalBundle) {
+            const reader = nextReader(deps.personalBundle);
+            const hits = await hybridSearch(reader, 'personal', args.query, deps.embedder);
+            const tagged = hits.map((h) => ({
+                id: h.id, text: h.text, source_uri: h.source_uri, score: h.score,
+                confidence: h.confidence, title: h.title, section_path: h.section_path,
+                ...(scope === 'both' ? { source_scope: 'personal' } : {}),
+            }));
+            allHits.push(...tagged);
+        }
+        // For scope='both', re-sort merged results by score descending
+        if (scope === 'both') {
+            allHits.sort((a, b) => b.score - a.score);
+        }
+        const fit = fitResults(allHits, maxTokens, (h) => JSON.stringify(h), (h) => h.id, (h) => h.source_uri);
+        const envelope = buildEnvelope({
+            result: fit.kept.map((item) => {
+                if ('too_large' in item)
+                    return item;
+                return item;
+            }),
+            tokensBudgeted: fit.tokensBudgeted,
+            tokensUsed: 0,
+            resultsTruncated: fit.truncated,
+            scope,
+            queryTimeMs: timer.end(),
+        });
+        const json = JSON.stringify(envelope);
+        envelope.meta.tokens_used = countEnvelopeTokens(json);
+        return wrapText(envelope);
+    };
+}
+function wrapText(envelope) {
+    return { content: [{ type: 'text', text: JSON.stringify(envelope) }] };
+}
+//# sourceMappingURL=search.js.map

package/dist/mcp/tools/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/mcp/tools/search.ts"],"names":[],"mappings":"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"}

package/dist/observability/audit.d.ts

@@ -0,0 +1,25 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+/**
+ * Audit log writer with scope-split JSONL mirror.
+ *
+ * Per CLAUDE.md §Security #7:
+ *   - scope='project' → kg_audit table in project .kg/kg.db + .kg/audit.jsonl
+ *   - scope='personal' or 'both' → kg_audit table in ~/.kg/kg.db + ~/.kg/audit.jsonl
+ *   - NEVER write personal query text to a path inside the project repo
+ */
+export interface AuditEntry {
+    toolName: string;
+    scopeRequested: string;
+    callerCtx?: string;
+    responseTokens?: number;
+    error?: string;
+}
+/**
+ * Write an audit row to the appropriate DB and mirror to JSONL.
+ *
+ * @param writer    The DB writer for the scope-appropriate bundle.
+ * @param jsonlPath The path for the JSONL mirror file.
+ * @param entry     Audit entry data.
+ */
+export declare function writeAuditRow(writer: BetterSqliteDatabase, jsonlPath: string | undefined, entry: AuditEntry): void;
+//# sourceMappingURL=audit.d.ts.map

package/dist/observability/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAIvE;;;;;;;GAOG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,UAAU,GAChB,IAAI,CAmCN"}