@alan512/experienceengine 0.1.3 → 0.2.0

package/dist/adapters/codex/mcp-server.js

@@ -9,31 +9,38 @@ import { ExperienceOperationalActionsService, } from "../../interaction/operatio
 import { ExperienceStateArtifactService } from "../../interaction/state-artifact-service.js";
 import { ExperienceRuntimeService } from "../../runtime/service.js";
 import { fetchLatestGitHubReleaseStatus } from "../../version/remote-release.js";
+import { createCodexActionRegistry } from "./action-registry.js";
+import { createCodexBrokerFacade, executeCodexActionSchema, listCodexActionsSchema, prepareCodexActionSchema } from "./broker-tools.js";
 const NODE_STATES = ["candidate", "priority_candidate", "active", "cooling", "retired"];
 const NODE_TYPES = ["strategy", "warning"];
 const EXPERIENCE_ADAPTERS = ["openclaw", "claude-code", "codex"];
 const HIGH_IMPACT_OPERATIONS = ["install", "repair", "upgrade"];
 const buildExperienceCapabilities = () => ({
-    model: "agent-first",
-    principles: [
-        "Users should talk to the host agent instead of memorizing ee CLI commands.",
-        "Low-risk read and preview operations should be direct MCP tools.",
-        "High-risk write operations should use plan -> review -> confirm flows."
+    core_actions: [
+        "experienceengine_lookup_hints",
+        "experienceengine_explain_last_decision",
+        "experienceengine_record_tool_result",
+        "experienceengine_finalize_task",
+        "experienceengine_feedback_last",
+        "experienceengine_get_capabilities",
+        "experienceengine_doctor"
     ],
-    prompts: [
-        "experienceengine_review_repo_status"
-    ],
-    resources: [
+    routine_read_surfaces: [
+        "experienceengine://doctor/{adapter}",
         "experienceengine://capabilities",
-        "experienceengine://repo-summary",
         "experienceengine://last",
-        "experienceengine://learning/summary"
+        "experienceengine://repo-summary"
+    ],
+    advanced_actions: [
+        "brokered admin actions",
+        "brokered maintenance actions",
+        "brokered inspect actions"
     ],
-    cliFallbacks: [
+    high_risk_actions: [
         "install / repair / upgrade",
-        "backup / export / import / rollback",
-        "maintenance commands"
-    ]
+        "backup / export / import / rollback"
+    ],
+    surface_model: "public core loop + public routine reads + brokered long-tail actions"
 });
 const createCodexRuntime = (options = {}) => {
     const paths = resolveExperienceEnginePaths({
@@ -48,7 +55,7 @@ const createCodexRuntime = (options = {}) => {
     }, {
         env: options.env ?? process.env,
         homeDir: options.homeDir
-    }));
+    }), undefined, options.runtimeOptions);
 };
 const createCodexInteractionService = (options = {}) => {
     const paths = resolveExperienceEnginePaths({
@@ -90,6 +97,23 @@ const toTextToolResult = (result) => ({
         }
     ]
 });
+const toNoticeAwareToolResult = (result) => ({
+    content: [
+        ...(result.notice
+            ? [
+                {
+                    type: "text",
+                    text: result.notice
+                }
+            ]
+            : []),
+        {
+            type: "text",
+            text: JSON.stringify(result ?? null, null, 2)
+        }
+    ],
+    structuredContent: result
+});
 const toStructuredToolResult = (result) => ({
     content: [
         {
@@ -108,19 +132,6 @@ const toJsonResourceResult = (uri, result) => ({
         }
     ]
 });
-const parseRecentMode = (value) => {
-    if (value === "all" || value === "injected") {
-        return value;
-    }
-    throw new Error(`Unsupported recent mode: ${value}`);
-};
-const parsePositiveLimit = (value) => {
-    const parsed = Number(value);
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-        throw new Error(`Invalid positive limit: ${value}`);
-    }
-    return parsed;
-};
 const parseNodeState = (value) => {
     if (NODE_STATES.includes(value)) {
         return value;
@@ -172,7 +183,8 @@ const summarizeTrust = (scorecard) => {
     if (!scorecard.riskLevel || !primaryNode?.state) {
         return undefined;
     }
-    return `${scorecard.riskLevel}-risk ${primaryNode.state} guidance with ${primaryNode.helped ?? 0} helped and ${primaryNode.harmed ?? 0} harmed signal(s).`;
+    const confidence = scorecard.confidence ? ` ${scorecard.confidence}-confidence` : "";
+    return `${scorecard.riskLevel}-risk${confidence} ${primaryNode.state} guidance with ${primaryNode.helped ?? 0} helped and ${primaryNode.harmed ?? 0} harmed signal(s).`;
 };
 const summarizeRetrievalNotes = (scorecard) => {
     const notes = [];
@@ -186,6 +198,16 @@ const summarizeRetrievalNotes = (scorecard) => {
     if (scorecard.fastPathApplied) {
         notes.push("A strong candidate fast path was used.");
     }
+    const topCandidate = scorecard.topCandidates?.[0];
+    if (topCandidate?.retrievalReasons?.length) {
+        notes.push(`Top retrieval signals: ${topCandidate.retrievalReasons.slice(0, 2).join(", ")}.`);
+    }
+    if (topCandidate?.policyReasons?.length) {
+        notes.push(`Top policy signals: ${topCandidate.policyReasons.slice(0, 2).join(", ")}.`);
+    }
+    if (scorecard.rejectedCandidates?.length) {
+        notes.push(`Runner-up candidates withheld: ${scorecard.rejectedCandidates.map((candidate) => candidate.id).join(", ")}.`);
+    }
     return notes;
 };
 const summarizeScorecard = (scorecard) => scorecard
@@ -196,6 +218,13 @@ const summarizeScorecard = (scorecard) => scorecard
         actionReason: summarizeActionReason(scorecard),
         trustSummary: summarizeTrust(scorecard),
         retrievalNotes: summarizeRetrievalNotes(scorecard),
+        confidence: scorecard.confidence,
+        budgetClass: scorecard.budgetClass,
+        selectedCandidateIds: scorecard.selectedCandidateIds,
+        rejectedCandidates: scorecard.rejectedCandidates?.slice(0, 3).map((candidate) => ({
+            id: candidate.id,
+            reasonCodes: candidate.reasonCodes
+        })) ?? [],
         reasons: scorecard.reasons?.slice(0, 2),
         nodes: scorecard.nodes?.slice(0, 3).map((node) => ({
             id: node.id,
@@ -264,6 +293,9 @@ export const createCodexBehaviorLoop = (options = {}) => {
                     ? "If the injected guidance helped or harmed this task, call experienceengine_quick_feedback."
                     : undefined
             };
+        },
+        async waitForBackgroundLearning() {
+            await runtime.waitForBackgroundLearning();
         }
     };
 };
@@ -297,6 +329,9 @@ export const createCodexInteractionSurface = (options = {}) => {
         async inspectRepoSummary(args = {}) {
             return interaction.inspectRepoSummary(args.cwd);
         },
+        async explainLastDecision(args) {
+            return interaction.explainLastDecision(args.cwd, args.userMessage);
+        },
         async feedbackLast(args) {
             return interaction.feedbackLast(args.feedback);
         },
@@ -327,9 +362,16 @@ export const createCodexMcpServer = (options = {}) => {
     const operationalSurface = createCodexOperationalService(options);
     const operationalActions = createCodexOperationalActionsService(options);
     const stateArtifacts = createCodexStateArtifactService(options);
+    const actionRegistry = createCodexActionRegistry({
+        interactionSurface,
+        operationalSurface,
+        operationalActions,
+        stateArtifacts
+    });
+    const brokerFacade = createCodexBrokerFacade(actionRegistry);
     const server = new McpServer({
         name: "experienceengine",
-        version: "0.1.3"
+        version: "0.2.0"
     });
     server.registerResource("experienceengine_doctor", new ResourceTemplate("experienceengine://doctor/{adapter}", {
         list: undefined,
@@ -341,43 +383,14 @@ export const createCodexMcpServer = (options = {}) => {
         description: "Structured ExperienceEngine adapter health and installation state.",
         mimeType: "application/json"
     }, async (uri, variables) => toJsonResourceResult(uri.toString(), await operationalSurface.inspectDoctor(parseAdapter(String(variables.adapter)))));
-    server.registerResource("experienceengine_updates_latest", new ResourceTemplate("experienceengine://updates/latest/{adapter}", {
-        list: undefined,
-        complete: {
-            adapter: () => [...EXPERIENCE_ADAPTERS]
-        }
-    }), {
-        title: "ExperienceEngine Latest Update State",
-        description: "Latest release/update status for an ExperienceEngine adapter context.",
-        mimeType: "application/json"
-    }, async (uri, variables) => toJsonResourceResult(uri.toString(), await operationalSurface.checkUpdate(parseAdapter(String(variables.adapter)))));
-    server.registerResource("experienceengine_backups", "experienceengine://backups", {
-        title: "ExperienceEngine Backup Inventory",
-        description: "Managed ExperienceEngine backups available for rollback or export review.",
-        mimeType: "application/json"
-    }, async (uri) => toJsonResourceResult(uri.toString(), stateArtifacts.listBackups()));
     server.registerResource("experienceengine_last", "experienceengine://last", {
         title: "ExperienceEngine Last Interaction",
         description: "The most recent persisted ExperienceEngine input record and any injected nodes.",
         mimeType: "application/json"
     }, async (uri) => toJsonResourceResult(uri.toString(), await interactionSurface.inspectLast()));
-    server.registerResource("experienceengine_recent", new ResourceTemplate("experienceengine://recent/{mode}/{limit}", {
-        list: undefined,
-        complete: {
-            mode: () => ["all", "injected"],
-            limit: () => ["5", "10", "20"]
-        }
-    }), {
-        title: "ExperienceEngine Recent History",
-        description: "Recent ExperienceEngine input records, optionally filtered to injected turns only.",
-        mimeType: "application/json"
-    }, async (uri, variables) => toJsonResourceResult(uri.toString(), await interactionSurface.inspectRecent({
-        mode: parseRecentMode(String(variables.mode ?? "all")),
-        limit: parsePositiveLimit(String(variables.limit ?? "10"))
-    })));
     server.registerResource("experienceengine_capabilities", "experienceengine://capabilities", {
         title: "ExperienceEngine Capabilities",
-        description: "Agent-first overview of ExperienceEngine MCP tools, guarded flows, prompts, and fallback boundaries.",
+        description: "Agent-first overview of ExperienceEngine MCP tools, routine reads, brokered actions, and fallback boundaries.",
         mimeType: "application/json"
     }, async (uri) => toJsonResourceResult(uri.toString(), buildExperienceCapabilities()));
     server.registerResource("experienceengine_repo_summary", "experienceengine://repo-summary", {
@@ -385,308 +398,21 @@ export const createCodexMcpServer = (options = {}) => {
         description: "Repo-level ExperienceEngine summary for the current scope, including benchmark and next action.",
         mimeType: "application/json"
     }, async (uri) => toJsonResourceResult(uri.toString(), await interactionSurface.inspectRepoSummary()));
-    server.registerResource("experienceengine_learning_summary", "experienceengine://learning/summary", {
-        title: "ExperienceEngine Learning Summary",
-        description: "Candidate, distillation, and formal node counts across the learning pipeline.",
-        mimeType: "application/json"
-    }, async (uri) => toJsonResourceResult(uri.toString(), await interactionSurface.inspectLearningSummary()));
-    server.registerResource("experienceengine_active_nodes", "experienceengine://nodes/active", {
-        title: "ExperienceEngine Active Nodes",
-        description: "All currently active ExperienceEngine nodes.",
-        mimeType: "application/json"
-    }, async (uri) => toJsonResourceResult(uri.toString(), await interactionSurface.listActiveNodes()));
-    server.registerResource("experienceengine_node", new ResourceTemplate("experienceengine://node/{id}", {
-        list: undefined
-    }), {
-        title: "ExperienceEngine Node Detail",
-        description: "A single ExperienceEngine node by id.",
-        mimeType: "application/json"
-    }, async (uri, variables) => toJsonResourceResult(uri.toString(), await interactionSurface.inspectNode({ nodeId: String(variables.id) })));
-    server.registerResource("experienceengine_nodes_by_state", new ResourceTemplate("experienceengine://nodes/state/{state}", {
-        list: undefined,
-        complete: {
-            state: () => [...NODE_STATES]
-        }
-    }), {
-        title: "ExperienceEngine Nodes By State",
-        description: "ExperienceEngine nodes filtered by lifecycle state.",
-        mimeType: "application/json"
-    }, async (uri, variables) => toJsonResourceResult(uri.toString(), await interactionSurface.listNodesByState({
-        state: parseNodeState(String(variables.state))
-    })));
-    server.registerResource("experienceengine_nodes_by_type", new ResourceTemplate("experienceengine://nodes/type/{type}", {
-        list: undefined,
-        complete: {
-            type: () => [...NODE_TYPES]
-        }
-    }), {
-        title: "ExperienceEngine Nodes By Type",
-        description: "ExperienceEngine nodes filtered by node type.",
-        mimeType: "application/json"
-    }, async (uri, variables) => toJsonResourceResult(uri.toString(), await interactionSurface.listNodesByType({
-        nodeType: parseNodeType(String(variables.type))
-    })));
-    server.registerPrompt("experienceengine_review_repo_status", {
-        title: "ExperienceEngine Review Repo Status",
-        description: "Guide the host agent to review the current repo's ExperienceEngine state before deciding what to do next."
-    }, async () => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: "Read experienceengine://repo-summary first. Summarize the repo verdict, suggested mode, and safest next action."
-                }
-            }
-        ]
-    }));
-    server.registerPrompt("experienceengine_review_capabilities", {
-        title: "ExperienceEngine Review Capabilities",
-        description: "Guide the host agent to review ExperienceEngine's agent-first MCP surface before using advanced ExperienceEngine operations."
-    }, async () => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: "Read experienceengine://capabilities first. Summarize which ExperienceEngine actions are direct tools, which need confirmation, and which stay CLI/operator-only."
-                }
-            }
-        ]
-    }));
-    server.registerPrompt("experienceengine_prepare_state_operation", {
-        title: "ExperienceEngine Prepare State Operation",
-        description: "Review a backup, export, import, or rollback plan before execution.",
-        argsSchema: {
-            operation: z.enum(["backup", "export", "import", "rollback"]),
-            backupId: z.string().optional(),
-            importPath: z.string().optional()
-        }
-    }, async ({ operation, backupId, importPath }) => {
-        const planTool = operation === "backup"
-            ? "experienceengine_plan_backup"
-            : operation === "export"
-                ? "experienceengine_plan_export"
-                : operation === "import"
-                    ? "experienceengine_plan_import"
-                    : "experienceengine_plan_rollback";
-        const suffix = operation === "rollback"
-            ? ` with backupId=${backupId ?? "<backup-id>"}`
-            : operation === "import"
-                ? ` with importPath=${importPath ?? "<snapshot-path>"}`
-                : "";
-        return {
-            messages: [
-                {
-                    role: "user",
-                    content: {
-                        type: "text",
-                        text: `Call ${planTool}${suffix} first. Review the summary, effects, and artifact path with the user. Only after explicit confirmation should you call experienceengine_execute_planned_state_operation with the returned planId and confirmationToken.`
-                    }
-                }
-            ]
-        };
-    });
-    server.registerPrompt("experienceengine_prepare_operational_change", {
-        title: "ExperienceEngine Prepare Operational Change",
-        description: "Plan a high-impact ExperienceEngine install, repair, or upgrade before execution.",
-        argsSchema: {
-            adapter: z.enum(EXPERIENCE_ADAPTERS),
-            operation: z.enum(HIGH_IMPACT_OPERATIONS)
-        }
-    }, async ({ adapter, operation }) => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `Call experienceengine_plan_${operation} with adapter=${adapter} first. Review the summary, effects, and commandHint with the user. Only after explicit confirmation should you call experienceengine_execute_planned_operation with the returned planId and confirmationToken.`
-                }
-            }
-        ]
-    }));
-    server.registerPrompt("experienceengine_show_last_intervention", {
-        title: "ExperienceEngine Show Last Intervention",
-        description: "Review the most recent ExperienceEngine interaction and summarize what happened."
-    }, async () => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: "Review the latest ExperienceEngine interaction in this Codex session. Summarize whether guidance was injected, which nodes were involved, and the recorded outcome. Use CLI fallback only if the host surface is unavailable."
-                }
-            },
-            {
-                role: "user",
-                content: createJsonResourceLink("experienceengine://last", "ExperienceEngine Last Interaction", "The latest persisted ExperienceEngine record and any resolved injected nodes.")
-            }
-        ]
-    }));
-    server.registerPrompt("experienceengine_review_recent_injected", {
-        title: "ExperienceEngine Review Recent Injected",
-        description: "Review recent ExperienceEngine turns that actually injected guidance.",
-        argsSchema: {
-            limit: z.string().optional()
-        }
-    }, async ({ limit }) => {
-        const resolvedLimit = limit ? parsePositiveLimit(limit) : 5;
-        const uri = `experienceengine://recent/injected/${resolvedLimit}`;
-        return {
-            messages: [
-                {
-                    role: "user",
-                    content: {
-                        type: "text",
-                        text: `Review the ${resolvedLimit} most recent ExperienceEngine turns that injected guidance. Summarize recurring wins and harmful repeats.`
-                    }
-                },
-                {
-                    role: "user",
-                    content: createJsonResourceLink(uri, "ExperienceEngine Recent Injected History", "Recent ExperienceEngine records filtered to injected turns.")
-                }
-            ]
-        };
-    });
-    server.registerPrompt("experienceengine_review_warning_nodes", {
-        title: "ExperienceEngine Review Warning Nodes",
-        description: "Review current warning nodes to assess whether they are still useful or noisy."
-    }, async () => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: "Review the current ExperienceEngine warning nodes. Identify stale warnings and any warning that appears noisy or over-firing."
-                }
-            },
-            {
-                role: "user",
-                content: createJsonResourceLink("experienceengine://nodes/type/warning", "ExperienceEngine Warning Nodes", "All ExperienceEngine nodes currently classified as warning nodes.")
-            }
-        ]
-    }));
-    server.registerPrompt("experienceengine_pause_current_project", {
-        title: "ExperienceEngine Pause Current Project",
-        description: "Guide the agent to pause ExperienceEngine interventions for the current project.",
-        argsSchema: {
-            cwd: z.string().optional()
-        }
-    }, async ({ cwd }) => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `Pause ExperienceEngine interventions for the current project${cwd ? ` at ${cwd}` : ""}. Confirm first, then call experienceengine_set_scope_intervention_state with action=disable and summarize the changed scope.`
-                }
-            }
-        ]
-    }));
-    server.registerPrompt("experienceengine_resume_current_project", {
-        title: "ExperienceEngine Resume Current Project",
-        description: "Guide the agent to resume ExperienceEngine interventions for the current project.",
-        argsSchema: {
-            cwd: z.string().optional()
-        }
-    }, async ({ cwd }) => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `Resume ExperienceEngine interventions for the current project${cwd ? ` at ${cwd}` : ""}. Confirm first, then call experienceengine_set_scope_intervention_state with action=enable and summarize the changed scope.`
-                }
-            }
-        ]
-    }));
-    server.registerPrompt("experienceengine_mark_last_experience_helpful", {
-        title: "ExperienceEngine Mark Last Experience Helpful",
-        description: "Guide the agent to mark the last injected experience as helpful."
-    }, async () => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: "Mark the last injected ExperienceEngine guidance as helpful in this Codex session. If needed, confirm first, call experienceengine_feedback_last with feedback=helped, and summarize updated nodes. Use CLI fallback only if the host path is unavailable."
-                }
-            }
-        ]
-    }));
-    server.registerPrompt("experienceengine_mark_last_experience_harmful", {
-        title: "ExperienceEngine Mark Last Experience Harmful",
-        description: "Guide the agent to mark the last injected experience as harmful."
-    }, async () => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: "Mark the last injected ExperienceEngine guidance as harmful in this Codex session. If needed, confirm first, call experienceengine_feedback_last with feedback=harmed, and summarize updated nodes. Use CLI fallback only if the host path is unavailable."
-                }
-            }
-        ]
-    }));
-    server.registerTool("experienceengine_plan_backup", {
-        title: "ExperienceEngine Plan Backup",
-        description: "Create a structured plan for backing up ExperienceEngine-managed state."
-    }, async () => toStructuredToolResult(stateArtifacts.planOperation({ operation: "backup" })));
-    server.registerTool("experienceengine_plan_export", {
-        title: "ExperienceEngine Plan Export",
-        description: "Create a structured plan for exporting ExperienceEngine-managed state."
-    }, async () => toStructuredToolResult(stateArtifacts.planOperation({ operation: "export" })));
-    server.registerTool("experienceengine_plan_import", {
-        title: "ExperienceEngine Plan Import",
-        description: "Create a structured plan for importing an ExperienceEngine snapshot.",
-        inputSchema: z.object({
-            importPath: z.string().min(1)
-        })
-    }, async ({ importPath }) => toStructuredToolResult(stateArtifacts.planOperation({ operation: "import", importPath })));
-    server.registerTool("experienceengine_plan_rollback", {
-        title: "ExperienceEngine Plan Rollback",
-        description: "Create a structured plan for rolling back ExperienceEngine state to a managed backup.",
-        inputSchema: z.object({
-            backupId: z.string().min(1)
-        })
-    }, async ({ backupId }) => toStructuredToolResult(stateArtifacts.planOperation({ operation: "rollback", backupId })));
-    server.registerTool("experienceengine_execute_planned_state_operation", {
-        title: "ExperienceEngine Execute Planned State Operation",
-        description: "Execute a previously planned ExperienceEngine backup, export, import, or rollback after explicit confirmation.",
-        inputSchema: z.object({
-            planId: z.string().min(1),
-            confirmationToken: z.string().min(1)
-        })
-    }, async ({ planId, confirmationToken }) => toStructuredToolResult(stateArtifacts.executePlannedOperation({ planId, confirmationToken })));
-    server.registerTool("experienceengine_plan_install", {
-        title: "ExperienceEngine Plan Install",
-        description: "Create a structured plan for installing ExperienceEngine on a supported adapter.",
-        inputSchema: z.object({
-            adapter: z.enum(EXPERIENCE_ADAPTERS)
-        })
-    }, async ({ adapter }) => toStructuredToolResult(operationalActions.planOperation({ adapter, operation: "install" })));
-    server.registerTool("experienceengine_plan_repair", {
-        title: "ExperienceEngine Plan Repair",
-        description: "Create a structured plan for repairing ExperienceEngine wiring on a supported adapter.",
-        inputSchema: z.object({
-            adapter: z.enum(EXPERIENCE_ADAPTERS)
-        })
-    }, async ({ adapter }) => toStructuredToolResult(operationalActions.planOperation({ adapter, operation: "repair" })));
-    server.registerTool("experienceengine_plan_upgrade", {
-        title: "ExperienceEngine Plan Upgrade",
-        description: "Create a structured plan for upgrading ExperienceEngine on a supported adapter.",
-        inputSchema: z.object({
-            adapter: z.enum(EXPERIENCE_ADAPTERS)
-        })
-    }, async ({ adapter }) => toStructuredToolResult(operationalActions.planOperation({ adapter, operation: "upgrade" })));
-    server.registerTool("experienceengine_execute_planned_operation", {
-        title: "ExperienceEngine Execute Planned Operation",
-        description: "Execute a previously planned high-impact ExperienceEngine operation after explicit user confirmation.",
-        inputSchema: z.object({
-            planId: z.string().min(1),
-            confirmationToken: z.string().min(1)
-        })
-    }, async ({ planId, confirmationToken }) => toStructuredToolResult(operationalActions.executePlannedOperation({ planId, confirmationToken })));
+    server.registerTool("experienceengine_list_actions", {
+        title: "ExperienceEngine List Actions",
+        description: "List brokered EE long-tail actions without exposing full schemas.",
+        inputSchema: listCodexActionsSchema
+    }, async (args) => toStructuredToolResult(brokerFacade.listActions(args)));
+    server.registerTool("experienceengine_prepare_action", {
+        title: "ExperienceEngine Prepare Action",
+        description: "Read detailed metadata for one brokered EE action.",
+        inputSchema: prepareCodexActionSchema
+    }, async (args) => toStructuredToolResult(brokerFacade.prepareAction(args)));
+    server.registerTool("experienceengine_execute_action", {
+        title: "ExperienceEngine Execute Action",
+        description: "Execute one brokered EE action through the internal action registry.",
+        inputSchema: executeCodexActionSchema
+    }, async (args) => toStructuredToolResult(await brokerFacade.executeAction(args)));
     server.registerTool("experienceengine_doctor", {
         title: "ExperienceEngine Doctor",
         description: "Inspect structured ExperienceEngine adapter health and installation state.",
@@ -698,26 +424,27 @@ export const createCodexMcpServer = (options = {}) => {
             openWorldHint: false
         }
     }, async ({ adapter }) => toTextToolResult(await operationalSurface.inspectDoctor(adapter)));
-    server.registerTool("experienceengine_check_update", {
-        title: "ExperienceEngine Check Update",
-        description: "Check structured ExperienceEngine release/update state for an adapter context.",
-        inputSchema: z.object({
-            adapter: z.enum(EXPERIENCE_ADAPTERS)
-        }),
-        annotations: {
-            readOnlyHint: true,
-            openWorldHint: true
-        }
-    }, async ({ adapter }) => toTextToolResult(await operationalSurface.checkUpdate(adapter)));
     server.registerTool("experienceengine_get_capabilities", {
         title: "ExperienceEngine Capabilities",
-        description: "Read the current ExperienceEngine MCP capabilities, including direct tools, guarded flows, prompts, and CLI-only fallbacks.",
+        description: "Read the current ExperienceEngine MCP capabilities, including direct tools, routine reads, brokered actions, and CLI-only fallbacks.",
         inputSchema: z.object({}),
         annotations: {
             readOnlyHint: true,
             openWorldHint: false
         }
     }, async () => toStructuredToolResult(buildExperienceCapabilities()));
+    server.registerTool("experienceengine_explain_last_decision", {
+        title: "ExperienceEngine Explain Last Decision",
+        description: "Explain why the latest ExperienceEngine intervention matched or stayed quiet for the current workspace.",
+        inputSchema: z.object({
+            cwd: z.string().optional(),
+            userMessage: z.string().min(1)
+        }),
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false
+        }
+    }, async ({ cwd, userMessage }) => toTextToolResult(await interactionSurface.explainLastDecision({ cwd, userMessage })));
     server.registerTool("experienceengine_lookup_hints", {
         title: "ExperienceEngine Lookup Hints",
         description: "Use once at task start for a real coding or debugging task to check whether ExperienceEngine has relevant prior guidance.",
@@ -726,7 +453,7 @@ export const createCodexMcpServer = (options = {}) => {
             prompt: z.string().min(1),
             sessionId: z.string().optional()
         })
-    }, async ({ cwd, prompt, sessionId }) => toTextToolResult(await behaviorLoop.lookupHints({ cwd, prompt, sessionId })));
+    }, async ({ cwd, prompt, sessionId }) => toNoticeAwareToolResult(await behaviorLoop.lookupHints({ cwd, prompt, sessionId })));
     server.registerTool("experienceengine_record_tool_result", {
         title: "ExperienceEngine Record Tool Result",
         description: "Record only important tool outcomes that changed the task direction, especially notable shell, test, build, or edit results, before finalization.",
@@ -764,53 +491,6 @@ export const createCodexMcpServer = (options = {}) => {
             nodeId: z.string().optional()
         })
     }, async ({ feedback }) => toStructuredToolResult(await interactionSurface.feedbackLast({ feedback })));
-    server.registerTool("experienceengine_feedback_node", {
-        title: "ExperienceEngine Feedback Node",
-        description: "Record helped or harmed feedback for a specific ExperienceEngine node.",
-        inputSchema: z.object({
-            nodeId: z.string().min(1),
-            feedback: z.enum(["helped", "harmed"])
-        }),
-        outputSchema: z.object({
-            status: z.enum(["updated", "not_found"]),
-            feedback: z.enum(["helped", "harmed"]).optional(),
-            nodeIds: z.array(z.string()).optional(),
-            reason: z.enum(["last_injected_missing", "node_missing"]).optional(),
-            nodeId: z.string().optional()
-        })
-    }, async ({ nodeId, feedback }) => toStructuredToolResult(await interactionSurface.feedbackNode({ nodeId, feedback })));
-    server.registerTool("experienceengine_set_scope_intervention_state", {
-        title: "ExperienceEngine Set Scope Intervention State",
-        description: "Enable or disable ExperienceEngine interventions for the provided working directory scope.",
-        inputSchema: z.object({
-            action: z.enum(["enable", "disable"]),
-            cwd: z.string().optional()
-        }),
-        outputSchema: z.object({
-            scopeId: z.string(),
-            scopeName: z.string(),
-            rootPath: z.string().optional(),
-            isDisabled: z.boolean(),
-            changed: z.boolean()
-        })
-    }, async ({ action, cwd }) => toStructuredToolResult(action === "disable"
-        ? await interactionSurface.disableScope({ cwd })
-        : await interactionSurface.enableScope({ cwd })));
-    server.registerTool("experienceengine_set_node_lifecycle", {
-        title: "ExperienceEngine Set Node Lifecycle",
-        description: "Move a specific ExperienceEngine node into cooling or retired lifecycle state.",
-        inputSchema: z.object({
-            action: z.enum(["cool", "retire"]),
-            nodeId: z.string().min(1)
-        }),
-        outputSchema: z.object({
-            status: z.enum(["updated", "not_found"]),
-            nodeId: z.string(),
-            state: z.enum(["candidate", "priority_candidate", "active", "cooling", "retired"]).optional()
-        })
-    }, async ({ action, nodeId }) => toStructuredToolResult(action === "cool"
-        ? await interactionSurface.coolNode({ nodeId })
-        : await interactionSurface.retireNode({ nodeId })));
     return server;
 };
 export const runCodexMcpServer = async () => {