@mirnoorata/codexa 0.2.0

package/dist/mcp/tool-registry.d.ts

@@ -0,0 +1,269 @@
+export type McpToolTier = "primary" | "advanced";
+export type McpToolPhase = "orientation" | "brief" | "plan" | "review" | "verify" | "inspect" | "diagnose" | "risk" | "memory";
+/** Typical structured-output size, as a routing hint for agents choosing the cheapest sufficient tool. */
+export type McpToolCost = "compact" | "medium" | "large";
+export interface McpToolRegistryEntry {
+    name: string;
+    title: string;
+    description: string;
+    tier: McpToolTier;
+    phase: McpToolPhase;
+    cost: McpToolCost;
+    writeEffects: string;
+    readOnly: boolean;
+    useWhen: string;
+    avoidWhen: string;
+    nextToolUse: string[];
+}
+export declare const MCP_TOOL_REGISTRY: readonly [{
+    readonly name: "session_context";
+    readonly title: "Codexa session context";
+    readonly description: "Orient at session start or resume: project focus, dirty groups, likely workflows, and the next Codexa call to make. Alias of focus_brief. Compact output.";
+    readonly tier: "primary";
+    readonly phase: "orientation";
+    readonly cost: "compact";
+    readonly writeEffects: "session-memory-auto";
+    readonly readOnly: false;
+    readonly useWhen: "Start or resume work in a repo and choose the next focused Codexa call.";
+    readonly avoidWhen: "You already have an explicit file or symbol target; use task_brief or change_plan instead.";
+    readonly nextToolUse: ["search", "task_brief"];
+}, {
+    readonly name: "search";
+    readonly title: "Codexa hybrid semantic search";
+    readonly description: "First-class target discovery when the task or identifier is ambiguous: one bounded hybrid pass (raw, exact, symbol, ranking; semantic only when configured) with likely tests and value/gap labels. Medium output; cheaper than context_pack.";
+    readonly tier: "primary";
+    readonly phase: "inspect";
+    readonly cost: "medium";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Before task_brief when the target is unclear, when a prompt is broad, or when you need one hybrid semantic/raw pass instead of repeated searches.";
+    readonly avoidWhen: "You already have precise files/symbols and need edit planning, drift review, or verification proof.";
+    readonly nextToolUse: ["task_brief", "change_plan"];
+}, {
+    readonly name: "task_brief";
+    readonly title: "Codexa task brief";
+    readonly description: "Default pre-edit context once a target or bounded task is known: read-first files, impact expansion, risks, likely tests, freshness, confidence labels, snippets. Medium output.";
+    readonly tier: "primary";
+    readonly phase: "brief";
+    readonly cost: "medium";
+    readonly writeEffects: "session-memory-auto";
+    readonly readOnly: false;
+    readonly useWhen: "Before editing, debugging, or reviewing a specific task after search/session context has supplied a plausible target.";
+    readonly avoidWhen: "The target is still unclear; run first-class search or provide explicit files first.";
+    readonly nextToolUse: ["change_plan"];
+}, {
+    readonly name: "change_plan";
+    readonly title: "Codexa change plan";
+    readonly description: "Plan a non-trivial edit; set saveSnapshot=true before editing so post_edit_review can detect drift. Returns plan targets, tests, freshness, and known gaps. Medium output.";
+    readonly tier: "primary";
+    readonly phase: "plan";
+    readonly cost: "medium";
+    readonly writeEffects: "task-snapshot-cache";
+    readonly readOnly: false;
+    readonly useWhen: "Before non-trivial edits; pass saveSnapshot=true to enable post-edit drift checks.";
+    readonly avoidWhen: "After edits are already made; use post_edit_review for dirty-tree accountability.";
+    readonly nextToolUse: ["post_edit_review"];
+}, {
+    readonly name: "post_edit_review";
+    readonly title: "Codexa post-edit review";
+    readonly description: "Go-to post-edit review gate: compares the dirty tree against the change_plan snapshot for planned-vs-actual drift, symbol/risk deltas, affected callers/tests/workflows, and tests still unaccounted for. Pass the snapshot task id plus commands that actually ran. MCP calls do not persist outcome files. Large output, budget-compacted.";
+    readonly tier: "primary";
+    readonly phase: "review";
+    readonly cost: "large";
+    readonly writeEffects: "session-memory-auto";
+    readonly readOnly: false;
+    readonly useWhen: "Immediately after edits and before final response; pass the saved change_plan task id plus commands/tests that actually ran.";
+    readonly avoidWhen: "Before editing or without a meaningful diff to review.";
+    readonly nextToolUse: ["test_plan"];
+}, {
+    readonly name: "test_plan";
+    readonly title: "Codexa test plan";
+    readonly description: "Recommend targeted tests for the current diff or top-ranked files. Recommendations only, not execution evidence. Compact output.";
+    readonly tier: "primary";
+    readonly phase: "verify";
+    readonly cost: "compact";
+    readonly writeEffects: "session-memory-auto";
+    readonly readOnly: false;
+    readonly useWhen: "Select verification for the current diff or after post_edit_review.";
+    readonly avoidWhen: "You need proof that tests ran; recommendations are not execution evidence.";
+    readonly nextToolUse: [];
+}, {
+    readonly name: "workflow_path";
+    readonly title: "Codexa workflow path";
+    readonly description: "Trace route/job/manifest workflow paths related to a query, file, or symbol. Medium output.";
+    readonly tier: "advanced";
+    readonly phase: "inspect";
+    readonly cost: "medium";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Inspect route, job, manifest, or workflow traces for a focused runtime path.";
+    readonly avoidWhen: "You only need startup orientation; session_context is cheaper.";
+    readonly nextToolUse: ["task_brief", "change_plan"];
+}, {
+    readonly name: "freshness";
+    readonly title: "Codexa freshness";
+    readonly description: "Report whether the Codexa index is present, fresh, stale, or missing. Compact, read-only.";
+    readonly tier: "advanced";
+    readonly phase: "diagnose";
+    readonly cost: "compact";
+    readonly writeEffects: "none";
+    readonly readOnly: true;
+    readonly useWhen: "Check whether indexed artifacts are present, fresh, stale, or missing.";
+    readonly avoidWhen: "You need task-specific context; use task_brief after freshness is known.";
+    readonly nextToolUse: ["task_brief"];
+}, {
+    readonly name: "repo_map";
+    readonly title: "Codexa repo map";
+    readonly description: "Ranked map of top modules and files for orientation. Compact output.";
+    readonly tier: "advanced";
+    readonly phase: "orientation";
+    readonly cost: "compact";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Get a ranked repository map or module overview.";
+    readonly avoidWhen: "You need edit-ready task context; task_brief carries more proof.";
+    readonly nextToolUse: ["task_brief"];
+}, {
+    readonly name: "find_context";
+    readonly title: "Codexa find context";
+    readonly description: "Locate files, symbols, and usage sites matching a precise query. Compact output; cheaper than search when the name is already known.";
+    readonly tier: "advanced";
+    readonly phase: "inspect";
+    readonly cost: "compact";
+    readonly writeEffects: "session-memory-auto";
+    readonly readOnly: false;
+    readonly useWhen: "Find matching files, symbols, and usage sites for a precise query.";
+    readonly avoidWhen: "You need dirty-diff review or saved edit planning.";
+    readonly nextToolUse: ["task_brief"];
+}, {
+    readonly name: "context_pack";
+    readonly title: "Codexa context pack";
+    readonly description: "Largest evidence packet for one task: focus files, bounded impact expansion, evidence snippets, impact groups, tests, freshness, provenance. Use only when task_brief is not enough. Large output.";
+    readonly tier: "advanced";
+    readonly phase: "brief";
+    readonly cost: "large";
+    readonly writeEffects: "session-memory-auto";
+    readonly readOnly: false;
+    readonly useWhen: "Build a larger task-shaped packet with snippets, impact, tests, and provenance.";
+    readonly avoidWhen: "A small first-pass task_brief is enough.";
+    readonly nextToolUse: ["change_plan"];
+}, {
+    readonly name: "focus_brief";
+    readonly title: "Codexa focus brief";
+    readonly description: "Classify a broad natural-language task, pick likely subsystems, and recommend the next Codexa call. Compact output.";
+    readonly tier: "advanced";
+    readonly phase: "orientation";
+    readonly cost: "compact";
+    readonly writeEffects: "session-memory-auto";
+    readonly readOnly: false;
+    readonly useWhen: "Classify a broad natural-language task and choose likely subsystems.";
+    readonly avoidWhen: "You already know exact files or symbols.";
+    readonly nextToolUse: ["task_brief", "search"];
+}, {
+    readonly name: "impact";
+    readonly title: "Codexa impact";
+    readonly description: "Blast-radius evidence for one file or symbol; traversal depth auto-scales with changeType (rename/delete reach deeper than style). Medium output.";
+    readonly tier: "advanced";
+    readonly phase: "inspect";
+    readonly cost: "medium";
+    readonly writeEffects: "session-memory-auto";
+    readonly readOnly: false;
+    readonly useWhen: "Inspect blast radius for one file or symbol before an API, behavior, rename, or delete change.";
+    readonly avoidWhen: "No target is known; use search or task_brief first.";
+    readonly nextToolUse: ["change_plan"];
+}, {
+    readonly name: "diff_impact";
+    readonly title: "Codexa diff impact";
+    readonly description: "Group the current dirty git diff into impact modules before review or verification. Medium output.";
+    readonly tier: "advanced";
+    readonly phase: "inspect";
+    readonly cost: "medium";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Group the current dirty tree before review or verification.";
+    readonly avoidWhen: "The tree is clean or you need a saved-snapshot drift review.";
+    readonly nextToolUse: ["post_edit_review", "test_plan"];
+}, {
+    readonly name: "symbol_context";
+    readonly title: "Codexa symbol context";
+    readonly description: "Proof-carrying neighborhood for one symbol: callers, callees, references, tests, risks, evidence. depth=1 is compact; depth=3 expands several-fold.";
+    readonly tier: "advanced";
+    readonly phase: "inspect";
+    readonly cost: "medium";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Inspect one symbol's definition and usage sites.";
+    readonly avoidWhen: "You need full file blast radius; use impact.";
+    readonly nextToolUse: ["impact"];
+}, {
+    readonly name: "callers";
+    readonly title: "Codexa callers";
+    readonly description: "Typed inbound graph edges (calls, references, imports, tests) for a file or symbol. Compact output.";
+    readonly tier: "advanced";
+    readonly phase: "inspect";
+    readonly cost: "compact";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Find typed inbound graph edges for a focused file or symbol.";
+    readonly avoidWhen: "You need outgoing dependencies; use callees.";
+    readonly nextToolUse: ["impact"];
+}, {
+    readonly name: "callees";
+    readonly title: "Codexa callees";
+    readonly description: "Typed outbound graph edges (calls, references, imports, tests, risks) for a file or symbol. Compact output.";
+    readonly tier: "advanced";
+    readonly phase: "inspect";
+    readonly cost: "compact";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Find typed outgoing graph edges for a focused file or symbol.";
+    readonly avoidWhen: "You need inbound usages; use callers.";
+    readonly nextToolUse: ["impact"];
+}, {
+    readonly name: "dependency_path";
+    readonly title: "Codexa dependency path";
+    readonly description: "Bounded typed graph path between two known files or symbols. Compact output.";
+    readonly tier: "advanced";
+    readonly phase: "inspect";
+    readonly cost: "compact";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Find a bounded graph path between two known files or symbols.";
+    readonly avoidWhen: "Either endpoint is unknown; use search first.";
+    readonly nextToolUse: ["change_plan"];
+}, {
+    readonly name: "placeholder_report";
+    readonly title: "Codexa placeholder report";
+    readonly description: "Indexed placeholder, dummy, TODO, and stub findings; tracked as risk signals that participate in post_edit_review deltas. Compact output.";
+    readonly tier: "advanced";
+    readonly phase: "risk";
+    readonly cost: "compact";
+    readonly writeEffects: "index-cache-if-auto-refresh";
+    readonly readOnly: false;
+    readonly useWhen: "Inspect TODO, stub, dummy, and not-implemented risk signals.";
+    readonly avoidWhen: "You need ordinary file localization.";
+    readonly nextToolUse: ["task_brief"];
+}, {
+    readonly name: "session_memory";
+    readonly title: "Codexa session memory";
+    readonly description: "Read, summarize, compact, or explicitly remember durable structured working memory for this Codex session. Cache-only; never mutates source. action=summary is the cheap overview. Compact output.";
+    readonly tier: "advanced";
+    readonly phase: "memory";
+    readonly cost: "compact";
+    readonly writeEffects: "explicit-memory-cache";
+    readonly readOnly: false;
+    readonly useWhen: "Read or write cache-only structured session memory for the current Codex workflow.";
+    readonly avoidWhen: "You need durable project docs or source changes.";
+    readonly nextToolUse: ["task_brief"];
+}];
+export type McpToolName = (typeof MCP_TOOL_REGISTRY)[number]["name"];
+export type McpToolCatalogEntry = Pick<McpToolRegistryEntry, "name" | "tier" | "phase" | "cost" | "writeEffects" | "readOnly" | "useWhen" | "avoidWhen" | "nextToolUse">;
+export declare const MCP_TOOL_CATALOG: readonly McpToolCatalogEntry[];
+export declare const MCP_TOOL_NAMES: readonly ("context_pack" | "task_brief" | "focus_brief" | "session_context" | "change_plan" | "post_edit_review" | "test_plan" | "repo_map" | "search" | "find_context" | "symbol_context" | "impact" | "diff_impact" | "callers" | "callees" | "dependency_path" | "workflow_path" | "placeholder_report" | "session_memory" | "freshness")[];
+export declare const PRIMARY_MCP_TOOL_NAMES: readonly ("task_brief" | "session_context" | "change_plan" | "post_edit_review" | "test_plan" | "search")[];
+export declare const ADVANCED_MCP_TOOL_NAMES: readonly ("context_pack" | "focus_brief" | "repo_map" | "find_context" | "symbol_context" | "impact" | "diff_impact" | "callers" | "callees" | "dependency_path" | "workflow_path" | "placeholder_report" | "session_memory" | "freshness")[];
+export declare const SOURCE_CONTEXT_MCP_TOOL_NAMES: readonly ("repo_map" | "search" | "symbol_context" | "diff_impact" | "callers" | "callees" | "dependency_path" | "workflow_path" | "placeholder_report")[];
+export declare const MEMORY_RECORDING_MCP_TOOL_NAMES: readonly ("context_pack" | "task_brief" | "focus_brief" | "session_context" | "post_edit_review" | "test_plan" | "find_context" | "impact")[];
+export declare const PRIMARY_CODEX_LOOP = "session_context -> search(if target unclear) -> task_brief -> change_plan(saveSnapshot) -> post_edit_review -> test_plan";
+export declare const NO_SOURCE_MUTATION_CONTRACT = "Codexa MCP tools may write Codexa cache artifacts, but must not mutate source files.";
+export declare function mcpToolRegistryEntry(name: string): McpToolRegistryEntry | undefined;

package/dist/mcp/tool-registry.js

@@ -0,0 +1,284 @@
+export const MCP_TOOL_REGISTRY = [
+    {
+        name: "session_context",
+        title: "Codexa session context",
+        description: "Orient at session start or resume: project focus, dirty groups, likely workflows, and the next Codexa call to make. Alias of focus_brief. Compact output.",
+        tier: "primary",
+        phase: "orientation",
+        cost: "compact",
+        writeEffects: "session-memory-auto",
+        readOnly: false,
+        useWhen: "Start or resume work in a repo and choose the next focused Codexa call.",
+        avoidWhen: "You already have an explicit file or symbol target; use task_brief or change_plan instead.",
+        nextToolUse: ["search", "task_brief"]
+    },
+    {
+        name: "search",
+        title: "Codexa hybrid semantic search",
+        description: "First-class target discovery when the task or identifier is ambiguous: one bounded hybrid pass (raw, exact, symbol, ranking; semantic only when configured) with likely tests and value/gap labels. Medium output; cheaper than context_pack.",
+        tier: "primary",
+        phase: "inspect",
+        cost: "medium",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Before task_brief when the target is unclear, when a prompt is broad, or when you need one hybrid semantic/raw pass instead of repeated searches.",
+        avoidWhen: "You already have precise files/symbols and need edit planning, drift review, or verification proof.",
+        nextToolUse: ["task_brief", "change_plan"]
+    },
+    {
+        name: "task_brief",
+        title: "Codexa task brief",
+        description: "Default pre-edit context once a target or bounded task is known: read-first files, impact expansion, risks, likely tests, freshness, confidence labels, snippets. Medium output.",
+        tier: "primary",
+        phase: "brief",
+        cost: "medium",
+        writeEffects: "session-memory-auto",
+        readOnly: false,
+        useWhen: "Before editing, debugging, or reviewing a specific task after search/session context has supplied a plausible target.",
+        avoidWhen: "The target is still unclear; run first-class search or provide explicit files first.",
+        nextToolUse: ["change_plan"]
+    },
+    {
+        name: "change_plan",
+        title: "Codexa change plan",
+        description: "Plan a non-trivial edit; set saveSnapshot=true before editing so post_edit_review can detect drift. Returns plan targets, tests, freshness, and known gaps. Medium output.",
+        tier: "primary",
+        phase: "plan",
+        cost: "medium",
+        writeEffects: "task-snapshot-cache",
+        readOnly: false,
+        useWhen: "Before non-trivial edits; pass saveSnapshot=true to enable post-edit drift checks.",
+        avoidWhen: "After edits are already made; use post_edit_review for dirty-tree accountability.",
+        nextToolUse: ["post_edit_review"]
+    },
+    {
+        name: "post_edit_review",
+        title: "Codexa post-edit review",
+        description: "Go-to post-edit review gate: compares the dirty tree against the change_plan snapshot for planned-vs-actual drift, symbol/risk deltas, affected callers/tests/workflows, and tests still unaccounted for. Pass the snapshot task id plus commands that actually ran. MCP calls do not persist outcome files. Large output, budget-compacted.",
+        tier: "primary",
+        phase: "review",
+        cost: "large",
+        writeEffects: "session-memory-auto",
+        readOnly: false,
+        useWhen: "Immediately after edits and before final response; pass the saved change_plan task id plus commands/tests that actually ran.",
+        avoidWhen: "Before editing or without a meaningful diff to review.",
+        nextToolUse: ["test_plan"]
+    },
+    {
+        name: "test_plan",
+        title: "Codexa test plan",
+        description: "Recommend targeted tests for the current diff or top-ranked files. Recommendations only, not execution evidence. Compact output.",
+        tier: "primary",
+        phase: "verify",
+        cost: "compact",
+        writeEffects: "session-memory-auto",
+        readOnly: false,
+        useWhen: "Select verification for the current diff or after post_edit_review.",
+        avoidWhen: "You need proof that tests ran; recommendations are not execution evidence.",
+        nextToolUse: []
+    },
+    {
+        name: "workflow_path",
+        title: "Codexa workflow path",
+        description: "Trace route/job/manifest workflow paths related to a query, file, or symbol. Medium output.",
+        tier: "advanced",
+        phase: "inspect",
+        cost: "medium",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Inspect route, job, manifest, or workflow traces for a focused runtime path.",
+        avoidWhen: "You only need startup orientation; session_context is cheaper.",
+        nextToolUse: ["task_brief", "change_plan"]
+    },
+    {
+        name: "freshness",
+        title: "Codexa freshness",
+        description: "Report whether the Codexa index is present, fresh, stale, or missing. Compact, read-only.",
+        tier: "advanced",
+        phase: "diagnose",
+        cost: "compact",
+        writeEffects: "none",
+        readOnly: true,
+        useWhen: "Check whether indexed artifacts are present, fresh, stale, or missing.",
+        avoidWhen: "You need task-specific context; use task_brief after freshness is known.",
+        nextToolUse: ["task_brief"]
+    },
+    {
+        name: "repo_map",
+        title: "Codexa repo map",
+        description: "Ranked map of top modules and files for orientation. Compact output.",
+        tier: "advanced",
+        phase: "orientation",
+        cost: "compact",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Get a ranked repository map or module overview.",
+        avoidWhen: "You need edit-ready task context; task_brief carries more proof.",
+        nextToolUse: ["task_brief"]
+    },
+    {
+        name: "find_context",
+        title: "Codexa find context",
+        description: "Locate files, symbols, and usage sites matching a precise query. Compact output; cheaper than search when the name is already known.",
+        tier: "advanced",
+        phase: "inspect",
+        cost: "compact",
+        writeEffects: "session-memory-auto",
+        readOnly: false,
+        useWhen: "Find matching files, symbols, and usage sites for a precise query.",
+        avoidWhen: "You need dirty-diff review or saved edit planning.",
+        nextToolUse: ["task_brief"]
+    },
+    {
+        name: "context_pack",
+        title: "Codexa context pack",
+        description: "Largest evidence packet for one task: focus files, bounded impact expansion, evidence snippets, impact groups, tests, freshness, provenance. Use only when task_brief is not enough. Large output.",
+        tier: "advanced",
+        phase: "brief",
+        cost: "large",
+        writeEffects: "session-memory-auto",
+        readOnly: false,
+        useWhen: "Build a larger task-shaped packet with snippets, impact, tests, and provenance.",
+        avoidWhen: "A small first-pass task_brief is enough.",
+        nextToolUse: ["change_plan"]
+    },
+    {
+        name: "focus_brief",
+        title: "Codexa focus brief",
+        description: "Classify a broad natural-language task, pick likely subsystems, and recommend the next Codexa call. Compact output.",
+        tier: "advanced",
+        phase: "orientation",
+        cost: "compact",
+        writeEffects: "session-memory-auto",
+        readOnly: false,
+        useWhen: "Classify a broad natural-language task and choose likely subsystems.",
+        avoidWhen: "You already know exact files or symbols.",
+        nextToolUse: ["task_brief", "search"]
+    },
+    {
+        name: "impact",
+        title: "Codexa impact",
+        description: "Blast-radius evidence for one file or symbol; traversal depth auto-scales with changeType (rename/delete reach deeper than style). Medium output.",
+        tier: "advanced",
+        phase: "inspect",
+        cost: "medium",
+        writeEffects: "session-memory-auto",
+        readOnly: false,
+        useWhen: "Inspect blast radius for one file or symbol before an API, behavior, rename, or delete change.",
+        avoidWhen: "No target is known; use search or task_brief first.",
+        nextToolUse: ["change_plan"]
+    },
+    {
+        name: "diff_impact",
+        title: "Codexa diff impact",
+        description: "Group the current dirty git diff into impact modules before review or verification. Medium output.",
+        tier: "advanced",
+        phase: "inspect",
+        cost: "medium",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Group the current dirty tree before review or verification.",
+        avoidWhen: "The tree is clean or you need a saved-snapshot drift review.",
+        nextToolUse: ["post_edit_review", "test_plan"]
+    },
+    {
+        name: "symbol_context",
+        title: "Codexa symbol context",
+        description: "Proof-carrying neighborhood for one symbol: callers, callees, references, tests, risks, evidence. depth=1 is compact; depth=3 expands several-fold.",
+        tier: "advanced",
+        phase: "inspect",
+        cost: "medium",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Inspect one symbol's definition and usage sites.",
+        avoidWhen: "You need full file blast radius; use impact.",
+        nextToolUse: ["impact"]
+    },
+    {
+        name: "callers",
+        title: "Codexa callers",
+        description: "Typed inbound graph edges (calls, references, imports, tests) for a file or symbol. Compact output.",
+        tier: "advanced",
+        phase: "inspect",
+        cost: "compact",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Find typed inbound graph edges for a focused file or symbol.",
+        avoidWhen: "You need outgoing dependencies; use callees.",
+        nextToolUse: ["impact"]
+    },
+    {
+        name: "callees",
+        title: "Codexa callees",
+        description: "Typed outbound graph edges (calls, references, imports, tests, risks) for a file or symbol. Compact output.",
+        tier: "advanced",
+        phase: "inspect",
+        cost: "compact",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Find typed outgoing graph edges for a focused file or symbol.",
+        avoidWhen: "You need inbound usages; use callers.",
+        nextToolUse: ["impact"]
+    },
+    {
+        name: "dependency_path",
+        title: "Codexa dependency path",
+        description: "Bounded typed graph path between two known files or symbols. Compact output.",
+        tier: "advanced",
+        phase: "inspect",
+        cost: "compact",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Find a bounded graph path between two known files or symbols.",
+        avoidWhen: "Either endpoint is unknown; use search first.",
+        nextToolUse: ["change_plan"]
+    },
+    {
+        name: "placeholder_report",
+        title: "Codexa placeholder report",
+        description: "Indexed placeholder, dummy, TODO, and stub findings; tracked as risk signals that participate in post_edit_review deltas. Compact output.",
+        tier: "advanced",
+        phase: "risk",
+        cost: "compact",
+        writeEffects: "index-cache-if-auto-refresh",
+        readOnly: false,
+        useWhen: "Inspect TODO, stub, dummy, and not-implemented risk signals.",
+        avoidWhen: "You need ordinary file localization.",
+        nextToolUse: ["task_brief"]
+    },
+    {
+        name: "session_memory",
+        title: "Codexa session memory",
+        description: "Read, summarize, compact, or explicitly remember durable structured working memory for this Codex session. Cache-only; never mutates source. action=summary is the cheap overview. Compact output.",
+        tier: "advanced",
+        phase: "memory",
+        cost: "compact",
+        writeEffects: "explicit-memory-cache",
+        readOnly: false,
+        useWhen: "Read or write cache-only structured session memory for the current Codex workflow.",
+        avoidWhen: "You need durable project docs or source changes.",
+        nextToolUse: ["task_brief"]
+    }
+];
+export const MCP_TOOL_CATALOG = MCP_TOOL_REGISTRY.map(({ name, tier, phase, cost, writeEffects, readOnly, useWhen, avoidWhen, nextToolUse }) => ({
+    name,
+    tier,
+    phase,
+    cost,
+    writeEffects,
+    readOnly,
+    useWhen,
+    avoidWhen,
+    nextToolUse
+}));
+export const MCP_TOOL_NAMES = Object.freeze(MCP_TOOL_REGISTRY.map((tool) => tool.name));
+export const PRIMARY_MCP_TOOL_NAMES = Object.freeze(MCP_TOOL_REGISTRY.filter((tool) => tool.tier === "primary").map((tool) => tool.name));
+export const ADVANCED_MCP_TOOL_NAMES = Object.freeze(MCP_TOOL_REGISTRY.filter((tool) => tool.tier === "advanced").map((tool) => tool.name));
+export const SOURCE_CONTEXT_MCP_TOOL_NAMES = Object.freeze(MCP_TOOL_REGISTRY.filter((tool) => tool.writeEffects === "index-cache-if-auto-refresh").map((tool) => tool.name));
+export const MEMORY_RECORDING_MCP_TOOL_NAMES = Object.freeze(MCP_TOOL_REGISTRY.filter((tool) => tool.writeEffects === "session-memory-auto").map((tool) => tool.name));
+export const PRIMARY_CODEX_LOOP = "session_context -> search(if target unclear) -> task_brief -> change_plan(saveSnapshot) -> post_edit_review -> test_plan";
+export const NO_SOURCE_MUTATION_CONTRACT = "Codexa MCP tools may write Codexa cache artifacts, but must not mutate source files.";
+export function mcpToolRegistryEntry(name) {
+    return MCP_TOOL_REGISTRY.find((tool) => tool.name === name);
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/mcp/tool-registry.js.map

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

package/dist/mcp/tools.d.ts

@@ -0,0 +1,53 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import type { QueryOptions, QueryResult } from "../types.js";
+import type { QuerySession } from "../query/session.js";
+export type McpOptionalQueryInput = Record<string, unknown> & {
+    semantic?: boolean;
+    semanticProvider?: "openai" | "local-command";
+    semanticModel?: string;
+    semanticDimensions?: number;
+    semanticTimeoutMs?: number;
+    semanticBatchSize?: number;
+    lsp?: boolean;
+    lspTimeoutMs?: number;
+    lspMaxFiles?: number;
+};
+type McpToolContext = string | {
+    toolName: string;
+    input?: Record<string, unknown>;
+    autoRecord?: boolean;
+};
+type ChangeType = "style" | "api" | "behavior" | "rename" | "delete" | "unknown";
+interface RegisterMcpToolsOptions {
+    server: McpServer;
+    queryOptions: QueryOptions;
+    outputSchema: ZodRawShapeCompat;
+    annotations: {
+        pureRead: ToolAnnotations;
+        sourceContext: ToolAnnotations;
+        cacheWrite: ToolAnnotations;
+        memoryWrite: ToolAnnotations;
+    };
+    schemas: {
+        changeType: z.ZodType<ChangeType>;
+        semanticQuery: z.ZodRawShape;
+        lspQuery: z.ZodRawShape;
+        confidence: z.ZodTypeAny;
+        evidenceTier: z.ZodTypeAny;
+        sessionMemoryKind: z.ZodTypeAny;
+        sessionMemoryProvenance: z.ZodTypeAny;
+        sessionMemoryStatus: z.ZodTypeAny;
+        sessionMemoryRef: z.ZodTypeAny;
+        sessionMemoryScope: z.ZodTypeAny;
+        sessionMemoryEvidence: z.ZodTypeAny;
+    };
+    toolQueryOptions: (input?: McpOptionalQueryInput) => QueryOptions;
+    runTool: (producer: (session: QuerySession) => Promise<QueryResult>, toolContext: McpToolContext) => Promise<CallToolResult>;
+    runFreshnessTool: () => Promise<CallToolResult>;
+}
+export declare const MCP_REGISTERED_TOOL_NAMES: readonly ("context_pack" | "task_brief" | "focus_brief" | "session_context" | "change_plan" | "post_edit_review" | "test_plan" | "repo_map" | "search" | "find_context" | "symbol_context" | "impact" | "diff_impact" | "callers" | "callees" | "dependency_path" | "workflow_path" | "placeholder_report" | "session_memory" | "freshness")[];
+export declare function registerMcpTools(options: RegisterMcpToolsOptions): void;
+export {};