@praxis-ai/praxis 0.1.2 → 0.1.3

package/dist/agentCore/index.d.ts

@@ -25,10 +25,10 @@ import { assemblePromptPack } from "../executionEngine/promptPack/promptAssemble
 import { assemblePromptContextMaterials, promptPackMaterialsForManifest } from "../runtimeImplementation/runtime.execEngine/promptContextAssembly.js";
 import { createObservationMaterial } from "../executionEngine/coreLogic/observationIntegrator.js";
 import { createMemoryPlane, memoryPlane } from "../memory_managementPool/index.js";
-import { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, mcp, planMcpHarnessExposure } from "../runtimeImplementation/runtime.mcpPlane/index.js";
+import { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, mcp, planMcpHarnessExposure } from "../runtimeImplementation/runtime.mcpPlane/index.js";
 export { PromptPack, PraxisAgent, PraxisAgentArchetype, STATE_PLANE_STANDARD_CONTROLS, append, compileAgent, endpoint, harness, inspectAgentManifest, loop, mainLoop, markdown, markdownFile, model, modelFleet, overwrite, policy, prepend, replaceLastLines, sandbox, session, statePlane, storage, tool, toolPolicies, tools, validateAgentManifest, type AgentCompileErrorCode, type AgentCompileResult, type AgentIdentity, type AgentManifest, type AgentManifestInspection, type AgentManifestValidationResult, type BaseToolPolicyDecision, type BaseToolPolicyMatrixSpec, type BaseToolPolicyProfile, type BaseToolPolicyRisk, type BaseToolPolicyRule, type HarnessSpec, type FrameworkCoreContractSpec, type LoopSpec, type MainLoopSpec, type ModelEndpointSpec, type ModelFleetSpec, type ModelSpec, type PolicySpec, type PraxisAgentClass, type PraxisAgentInput, type PromptMaterialSource, type PromptPackSpec, type PromptPatchSpec, type SandboxSpec, type SandboxIsolationLevel, type SandboxMountPolicy, type SandboxNetworkRuntimePolicy, type SandboxPlatformSupport, type SandboxPlatformSupportStatus, type SandboxProcessPolicy, type SandboxProviderFamily, type SessionSpec, type StatePlaneSpec, type StorageSpec, type ToolSpec, type ToolPolicyCustomInput, } from "../runtimeImplementation/runtimeAgentManifest.js";
-export { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, mcp, planMcpHarnessExposure, };
-export type { McpApplicationServerView, McpApplicationServerInput, McpApplicationStateView, McpHarnessExposurePlan, McpHarnessModuleSpec, McpHarnessServerMode, McpHarnessServerSpec, McpPlusApplicationServerInput, McpTransportSpec, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
+export { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, mcp, planMcpHarnessExposure, };
+export type { McpApplicationServerView, McpApplicationServerInput, McpApplicationStateView, McpHarnessExposurePlan, McpHarnessModuleSpec, McpHarnessServerMode, McpHarnessServerSpec, McpPlusLearnedProfile, McpPlusApplicationServerInput, McpPlusOverlayStore, McpPlusOverlayStoreKey, McpPlusProfileProposal, McpPlusProfileStore, McpPlusProfileStoreKey, McpPlusRuntimeOverlay, McpPlusSkillNote, McpPlusSkillStore, McpTransportSpec, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
 export { createMemoryPlane, memoryPlane, };
 export type { MemoryArtifactRef, MemoryIndexStatus, MemoryLayout, MemoryPlane, MemoryPlaneOptions, MemoryPolicyRisk, MemoryProfile, MemoryPromptGuide, MemoryReindexResult, MemoryRiskMetadata, MemoryScope, MemorySearchGuide, MemorySearchRequest, MemorySourceType, } from "../memory_managementPool/index.js";
 export { capabilities, capability, createProvisionPlan, dependencies, dependencyAuthoring, provisionRuntimeDescriptor, type CapabilityFallbackSpec, type CapabilityInput, type CapabilityKind, type CapabilityPolicySpec, type CapabilityReadiness, type CapabilitySpec, type CodeIntelligenceCapabilityInput, type ProvisionPlan, type SandboxCapabilityInput, } from "../runtimeImplementation/runtime.provisionPlane/index.js";

package/dist/agentCore/index.js

@@ -31,9 +31,9 @@ import { assemblePromptContextMaterials, promptPackMaterialsForManifest, } from
 import { createObservationMaterial, } from "../executionEngine/coreLogic/observationIntegrator.js";
 import { runtimeAuth, } from "../runtimeImplementation/runtime.authPlane/index.js";
 import { createMemoryPlane, memoryPlane, } from "../memory_managementPool/index.js";
-import { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, mcp, planMcpHarnessExposure, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
+import { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, mcp, planMcpHarnessExposure, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
 export { PromptPack, PraxisAgent, PraxisAgentArchetype, STATE_PLANE_STANDARD_CONTROLS, append, compileAgent, endpoint, harness, inspectAgentManifest, loop, mainLoop, markdown, markdownFile, model, modelFleet, overwrite, policy, prepend, replaceLastLines, sandbox, session, statePlane, storage, tool, toolPolicies, tools, validateAgentManifest, } from "../runtimeImplementation/runtimeAgentManifest.js";
-export { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, mcp, planMcpHarnessExposure, };
+export { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, mcp, planMcpHarnessExposure, };
 export { createMemoryPlane, memoryPlane, };
 export { capabilities, capability, createProvisionPlan, dependencies, dependencyAuthoring, provisionRuntimeDescriptor, } from "../runtimeImplementation/runtime.provisionPlane/index.js";
 export { component, createRuntimeComponentRegistry, lookupRuntimeComponent, officialRuntimeComponents, } from "../runtimeImplementation/runtime.componentPlane/index.js";

package/dist/applicationLayer/applicationRuntime.d.ts

@@ -1,5 +1,5 @@
 import { type AgentManifest, type BaseToolExecutorPort, type AgentToolCallProgressEvent, type RuntimeApprovalResolver, type RuntimeAgentReviewResolver, type RuntimeAuthResolver, type RuntimeAuthResolverRequest, type SandboxExecutionProviderPort, type CompactExecutor, type PreCompactGovernanceExecutor, type PraxisProjectRuntime } from "../agentCore/index.js";
-import { type McpApplicationServerInput, type McpHarnessModuleSpec, type McpPlusApplicationServerInput } from "../runtimeImplementation/runtime.mcpPlane/index.js";
+import { type McpApplicationServerInput, type McpHarnessModuleSpec, type McpPlusApplicationServerInput, type McpPlusOverlayStore, type McpPlusProfileStore, type McpPlusSkillStore } from "../runtimeImplementation/runtime.mcpPlane/index.js";
 import { type OpenAIV1ResponsesProviderCaller, type OpenAIV1ResponsesResult } from "../modelAdapter/actualInvocationLayer/openai/v1_responses.js";
 import type { OpenAiV1ChatCompletionsProviderCaller } from "../modelAdapter/actualInvocationLayer/openai/v1_chat_completions.js";
 import type { AnthropicV1MessagesProviderCaller } from "../modelAdapter/actualInvocationLayer/anthropic/v1_messages.js";
@@ -75,6 +75,13 @@ export type PraxisApplicationRuntimeOptions = {
     mcpServers?: readonly McpApplicationServerInput[];
     mcpPlusServers?: readonly McpPlusApplicationServerInput[];
     mcpModule?: McpHarnessModuleSpec;
+    mcpPlus?: {
+        projectId?: string;
+        profileStore?: McpPlusProfileStore;
+        overlayStore?: McpPlusOverlayStore;
+        skillStore?: McpPlusSkillStore;
+        reprofileConsecutiveIndexedCalls?: number;
+    };
     onApplicationToolEvent?: (event: PraxisApplicationEvent) => void | Promise<void>;
     initialConversations?: readonly PraxisApplicationInitialConversation[];
     foundationProject?: PraxisProjectRuntime;

package/dist/applicationLayer/applicationRuntime.js

@@ -2839,6 +2839,7 @@ export function createPraxisApplicationRuntime(options) {
                         agentReviewResolver: options.agentReviewResolver,
                         mcpServers: applicationMcpServerProfiles(applicationMcpModule),
                         mcpModule: applicationMcpModule,
+                        mcpPlus: options.mcpPlus,
                         storage: {
                             cwd: childSession.workingDirectory,
                             workspaceRoot: path.join(project.projectRoot, ".raxode"),
@@ -3466,6 +3467,7 @@ export function createPraxisApplicationRuntime(options) {
             agentReviewResolver: options.agentReviewResolver,
             mcpServers: applicationMcpServerProfiles(applicationMcpModule),
             mcpModule: applicationMcpModule,
+            mcpPlus: options.mcpPlus,
             storage: {
                 cwd: state.cwd,
                 workspaceRoot: path.join(project.projectRoot, ".raxode"),

package/dist/applicationLayer/index.d.ts

@@ -1,5 +1,6 @@
 export type { PraxisApplicationAttachment, PraxisApplicationAgentEntryView, PraxisApplicationAuxiliaryTaskInput, PraxisApplicationAuthProfileView, PraxisApplicationAuthState, PraxisApplicationCommand, PraxisApplicationCommandResult, PraxisApplicationContextTelemetry, PraxisApplicationEvent, PraxisApplicationEventKind, PraxisApplicationInputEnvelope, PraxisApplicationManifestView, PraxisApplicationModelState, PraxisApplicationPermissionProfile, PraxisApplicationReasoningEffort, PraxisApplicationRuntime, PraxisApplicationRuntimeMode, PraxisApplicationStatus, PraxisApplicationToolCatalogState, PraxisApplicationToolProfile, PraxisApplicationUsageTelemetry, PraxisApplicationViewModel, } from "./applicationContract.js";
 export { loadApplicationProject, type PraxisApplicationProject, type PraxisApplicationProjectDescriptor, type PraxisApplicationProjectResult, } from "./applicationProject.js";
 export { createApplicationProjectRuntime, createPraxisApplicationRuntime, type PraxisApplicationBaseToolIntegrationOptions, type CreateApplicationProjectRuntimeOptions, type PraxisApplicationInitialConversation, type PraxisApplicationInitialConversationMessage, type PraxisApplicationLiveProvider, type PraxisApplicationRuntimeOptions, } from "./applicationRuntime.js";
-export type { McpApplicationServerInput, McpPlusApplicationServerInput, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
+export type { McpApplicationServerInput, McpPlusLearnedProfile, McpPlusApplicationServerInput, McpPlusOverlayStore, McpPlusProfileProposal, McpPlusProfileStore, McpPlusRuntimeOverlay, McpPlusSkillNote, McpPlusSkillStore, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
+export { createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
 export { createApplicationRestServer, createApplicationWebSocketServer, createLocalApplicationTransport, describeApplicationRestTransport, describeApplicationWebSocketTransport, type PraxisApplicationRestServer, type PraxisApplicationWebSocketServer, type PraxisApplicationProtocolMessage, type PraxisApplicationRestRoute, type PraxisApplicationTransportClient, type PraxisApplicationTransportDescriptor, type PraxisApplicationTransportKind, type PraxisApplicationWebSocketMessage, } from "./applicationTransport.js";

package/dist/applicationLayer/index.js

@@ -4,4 +4,5 @@
  */
 export { loadApplicationProject, } from "./applicationProject.js";
 export { createApplicationProjectRuntime, createPraxisApplicationRuntime, } from "./applicationRuntime.js";
+export { createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
 export { createApplicationRestServer, createApplicationWebSocketServer, createLocalApplicationTransport, describeApplicationRestTransport, describeApplicationWebSocketTransport, } from "./applicationTransport.js";

package/dist/runtimeImplementation/praxisRuntimeKernel.d.ts

@@ -22,7 +22,7 @@ import { type RuntimeApprovalRecord, type RuntimeSessionSnapshot, type RuntimeSe
 import { type RaxStorageInitMode } from "./runtime.storagePlane/storagePlaneRuntime.js";
 import type { SandboxRemoteWorkerAdapter } from "./runtime.sandboxPlane/sandboxCommandRunner.js";
 import type { SandboxExecutionProviderPort } from "./runtime.sandboxPlane/sandboxPolicyMiddleware.js";
-import { type McpHarnessModuleSpec } from "./runtime.mcpPlane/index.js";
+import { type McpPlusOverlayStore, type McpPlusProfileStore, type McpPlusSkillStore, type McpHarnessModuleSpec } from "./runtime.mcpPlane/index.js";
 import type { McpRuntimeServerProfile } from "./runtime.execEngine/mcpRuntimeAdapter.js";
 export type PraxisRuntimeKernelErrorCode = "MANIFEST_COMPILE_FAILED" | "TEXT_INPUT_REJECTED" | "PROMPT_PACK_FAILED" | "MAIN_LOOP_INTERRUPTED" | "MODEL_INVOCATION_FAILED" | "MODEL_DECISION_FAILED" | "TOOL_INVOCATION_FAILED" | "PROCEDURE_INVOCATION_FAILED" | "APPROVAL_REQUIRED" | "SANDBOX_UNAVAILABLE" | "STORAGE_RESOLUTION_FAILED" | "TEXT_OUTPUT_REJECTED";
 export type PraxisRuntimeKernelError = {
@@ -52,6 +52,13 @@ export type PraxisRuntimeKernelOptions = {
     baseToolAdapters?: Partial<BaseToolExecutorPort>;
     mcpServers?: readonly McpRuntimeServerProfile[];
     mcpModule?: McpHarnessModuleSpec;
+    mcpPlus?: {
+        projectId?: string;
+        profileStore?: McpPlusProfileStore;
+        overlayStore?: McpPlusOverlayStore;
+        skillStore?: McpPlusSkillStore;
+        reprofileConsecutiveIndexedCalls?: number;
+    };
     baseToolPolicy?: RuntimeBaseToolExecutorPolicy;
     baseToolResourceLimits?: RuntimeBaseToolExecutorResourceLimits;
     store?: RuntimeSessionStateEventStore;

package/dist/runtimeImplementation/praxisRuntimeKernel.js

@@ -42,7 +42,7 @@ import { approvalInterfaceEnvelope, } from "../interfaceAdapter/interfaceEnvelop
 import { createInMemorySessionStateEventStore, createSqliteSessionStateEventStore, } from "./runtimeSessionStateEventStore.js";
 import { applyRaxStorageInitPlan, createStoragePlaneRuntime, } from "./runtime.storagePlane/storagePlaneRuntime.js";
 import { prepareSandboxRuntime, } from "./runtime.sandboxPlane/sandboxRuntimeProvider.js";
-import { buildMcpServerProfilesFromManifest, mcp, planMcpHarnessExposure, } from "./runtime.mcpPlane/index.js";
+import { buildMcpServerProfilesFromManifest, createInMemoryMcpPlusOverlayStore, createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, learnedProfileFromProposal, mcp, mcpHarnessModuleFrom, planMcpHarnessExposure, } from "./runtime.mcpPlane/index.js";
 async function inferFilesystemActionForTool(input) {
     if (input.toolId !== "patch.apply")
         return undefined;
@@ -290,9 +290,7 @@ function defaultMcpServerId(toolId, args) {
         return undefined;
     return readString(args.serverId) ?? "local-mcp";
 }
-function withRuntimeHarnessTools(manifest, dynamicTools) {
-    if (dynamicTools.length === 0)
-        return manifest;
+function withRuntimeHarnessToolLayer(manifest, dynamicTools, reason) {
     const byId = new Map();
     for (const tool of [...manifest.harness.tools, ...dynamicTools]) {
         byId.set(tool.toolId, tool);
@@ -305,6 +303,7 @@ function withRuntimeHarnessTools(manifest, dynamicTools) {
             metadata: {
                 ...manifest.harness.metadata,
                 runtimeMcpDynamicToolCount: dynamicTools.length,
+                runtimeMcpDynamicToolRefreshReason: reason,
             },
         },
     };
@@ -345,7 +344,246 @@ function normalizeMcpNativeToolDeclaration(tool) {
     const schema = isRecord(tool.inputSchema) ? tool.inputSchema : isRecord(tool.input_schema) ? tool.input_schema : {};
     return { name, description, inputSchema: schema };
 }
-async function discoverRuntimeMcpDynamicTools(manifest, executor) {
+function runtimeMcpPlusProjectId(input) {
+    if (typeof input.explicit === "string" && input.explicit.trim().length > 0)
+        return input.explicit.trim();
+    return `project.${createHash("sha256").update(path.resolve(input.workspaceRoot)).digest("hex").slice(0, 16)}`;
+}
+function mcpPlusOverlayToExposureState(overlay) {
+    if (overlay === undefined)
+        return {};
+    return {
+        mode: overlay.mode,
+        activeTools: [
+            ...overlay.activeTools,
+            ...(overlay.pendingReprofile ? ["mcp_plus.reprofile"] : []),
+        ],
+    };
+}
+function readStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim());
+}
+function proposalFromArgs(args, fallbackServerId) {
+    const rawToolCards = isRecord(args.toolCards) ? args.toolCards : undefined;
+    const toolCards = rawToolCards === undefined ? undefined : Object.fromEntries(Object.entries(rawToolCards).flatMap(([toolName, card]) => {
+        if (!isRecord(card))
+            return [];
+        return [[toolName, {
+                    title: readString(card.title),
+                    summary: readString(card.summary),
+                    keywords: readStringList(card.keywords),
+                }]];
+    }));
+    const rawSkillChapters = Array.isArray(args.skillChapters) ? args.skillChapters : [];
+    const proposal = {
+        serverId: readString(args.serverId) ?? fallbackServerId,
+        pinnedTools: readStringList(args.pinnedTools),
+        warmTools: readStringList(args.warmTools),
+        indexedTools: readStringList(args.indexedTools),
+        alwaysIndexTools: readStringList(args.alwaysIndexTools),
+        toolCards,
+        skillChapters: rawSkillChapters.flatMap((chapter) => {
+            if (!isRecord(chapter))
+                return [];
+            const id = readString(chapter.id);
+            const title = readString(chapter.title);
+            const summary = readString(chapter.summary);
+            return id === undefined || title === undefined || summary === undefined ? [] : [{ id, title, summary }];
+        }),
+        rationale: readString(args.rationale),
+    };
+    if (Object.hasOwn(args, "modeHint")) {
+        return {
+            ...proposal,
+            modeHint: args.modeHint,
+        };
+    }
+    return proposal;
+}
+function mcpPlusServerSpec(manifest, serverId) {
+    return mcpHarnessModuleFrom(manifest.harness)?.servers.find((server) => server.serverId === serverId);
+}
+function createRuntimeMcpPlusController(input) {
+    let nativeInventory = {};
+    async function loadOverlay(serverId, now) {
+        return await input.overlayStore.load({ sessionId: input.sessionId, serverId }) ?? {
+            serverId,
+            sessionId: input.sessionId,
+            mode: "expanded",
+            activeTools: [],
+            counters: { consecutiveIndexedToolCalls: {} },
+            updatedAt: now,
+        };
+    }
+    return {
+        async setNativeInventory(inventory) {
+            nativeInventory = inventory;
+        },
+        async learnedProfilesByServerId(manifest) {
+            const module = mcpHarnessModuleFrom(manifest.harness);
+            const profiles = {};
+            for (const server of module?.servers ?? []) {
+                if (server.mode !== "mcp-plus" || server.manifest !== undefined)
+                    continue;
+                profiles[server.serverId] = await input.profileStore.load({ projectId: input.projectId, serverId: server.serverId });
+            }
+            return profiles;
+        },
+        async exposureStateByServerId(manifest) {
+            const module = mcpHarnessModuleFrom(manifest.harness);
+            const states = {};
+            for (const server of module?.servers ?? []) {
+                if (server.mode !== "mcp-plus")
+                    continue;
+                states[server.serverId] = mcpPlusOverlayToExposureState(await input.overlayStore.load({ sessionId: input.sessionId, serverId: server.serverId }));
+            }
+            return states;
+        },
+        async callControlTool(control) {
+            if (control.controlName === "mcp_plus.init" || control.controlName === "mcp_plus.reprofile") {
+                const proposal = proposalFromArgs(control.args, control.serverId);
+                const nativeTools = nativeInventory[proposal.serverId] ?? [];
+                const existing = await input.profileStore.load({ projectId: input.projectId, serverId: proposal.serverId });
+                const learned = learnedProfileFromProposal({
+                    proposal,
+                    nativeTools,
+                    projectId: input.projectId,
+                    now: control.now,
+                    existing,
+                });
+                if (!learned.ok)
+                    return { ok: false, error: learned.error };
+                await input.profileStore.save({ projectId: input.projectId, serverId: proposal.serverId }, learned.profile);
+                const overlay = await loadOverlay(proposal.serverId, control.now);
+                await input.overlayStore.save({ sessionId: input.sessionId, serverId: proposal.serverId }, {
+                    ...overlay,
+                    mode: "expanded",
+                    activeTools: [],
+                    pendingReprofile: false,
+                    counters: { consecutiveIndexedToolCalls: {} },
+                    updatedAt: control.now,
+                    metadata: {
+                        ...(overlay.metadata ?? {}),
+                        lastProfileControl: control.controlName,
+                    },
+                });
+                return {
+                    ok: true,
+                    output: {
+                        accepted: true,
+                        serverId: proposal.serverId,
+                        projectId: input.projectId,
+                        schemaVersion: learned.profile.schemaVersion,
+                        controlName: control.controlName,
+                    },
+                    metadata: { serverId: proposal.serverId, projectId: input.projectId, controlName: control.controlName },
+                };
+            }
+            if (control.controlName === "mcp_plus.skill_read") {
+                const serverId = readString(control.args.serverId) ?? control.serverId;
+                const notes = await input.skillStore.read({ serverId, projectId: input.projectId }, {
+                    id: readString(control.args.id),
+                    chapter: readString(control.args.chapter),
+                });
+                return { ok: true, output: { serverId, projectId: input.projectId, notes } };
+            }
+            if (control.controlName === "mcp_plus.skill_write" || control.controlName === "mcp_plus.finish") {
+                const rawSkill = control.controlName === "mcp_plus.finish" && isRecord(control.args.skill)
+                    ? control.args.skill
+                    : control.args;
+                const serverId = readString(rawSkill.serverId) ?? readString(control.args.serverId) ?? control.serverId;
+                const chapter = readString(rawSkill.chapter);
+                const title = readString(rawSkill.title);
+                const summary = readString(rawSkill.summary);
+                if (chapter === undefined || title === undefined || summary === undefined) {
+                    return {
+                        ok: true,
+                        output: {
+                            accepted: false,
+                            serverId,
+                            projectId: input.projectId,
+                            reason: "No complete skill note was provided.",
+                        },
+                    };
+                }
+                const note = await input.skillStore.write({ serverId, projectId: input.projectId }, {
+                    chapter,
+                    title,
+                    summary,
+                    whenToUse: readString(rawSkill.whenToUse),
+                    do: readStringList(rawSkill.do),
+                    why: readString(rawSkill.why),
+                    avoid: readStringList(rawSkill.avoid),
+                    pitfalls: readStringList(rawSkill.pitfalls),
+                });
+                return { ok: true, output: { accepted: true, serverId, projectId: input.projectId, note } };
+            }
+            if (control.controlName === "mcp_plus.expand") {
+                const serverId = readString(control.args.server) ?? readString(control.args.serverId) ?? control.serverId;
+                const request = readString(control.args.request)?.toLowerCase() ?? "";
+                const server = mcpPlusServerSpec(control.manifest, serverId);
+                const profile = await input.profileStore.load({ projectId: input.projectId, serverId });
+                const indexedTools = server?.manifest?.exposure?.indexedTools ?? profile?.exposure.indexedTools ?? [];
+                const activatedTools = request.length === 0
+                    ? indexedTools
+                    : indexedTools.filter((toolName) => toolName.toLowerCase().includes(request));
+                const overlay = await loadOverlay(serverId, control.now);
+                await input.overlayStore.save({ sessionId: input.sessionId, serverId }, {
+                    ...overlay,
+                    mode: "expanded",
+                    activeTools: [...new Set([...overlay.activeTools, ...activatedTools])],
+                    updatedAt: control.now,
+                });
+                return { ok: true, output: { serverId, activatedTools, mode: "expanded" } };
+            }
+            return { ok: false, error: { code: "MCP_PLUS_CONTROL_UNKNOWN", message: `Unknown MCP+ control tool: ${control.controlName}`, publicSafe: true } };
+        },
+        async recordToolCall(record) {
+            if (!record.ok)
+                return false;
+            const toolSpec = record.manifest.harness.tools.find((tool) => tool.toolId === record.toolId);
+            if (toolSpec?.metadata?.toolProviderKind !== "mcp-static")
+                return false;
+            const serverId = readString(toolSpec.metadata.serverId);
+            const nativeToolName = readString(toolSpec.metadata.nativeToolName);
+            if (serverId === undefined || nativeToolName === undefined)
+                return false;
+            const server = mcpPlusServerSpec(record.manifest, serverId);
+            if (server?.mode !== "mcp-plus")
+                return false;
+            const profile = server.manifest === undefined
+                ? await input.profileStore.load({ projectId: input.projectId, serverId })
+                : undefined;
+            const indexedTools = new Set(server.manifest?.exposure?.indexedTools ?? profile?.exposure.indexedTools ?? []);
+            const overlay = await loadOverlay(serverId, record.now);
+            const consecutiveIndexedToolCalls = { ...overlay.counters.consecutiveIndexedToolCalls };
+            let pendingReprofile = overlay.pendingReprofile;
+            if (indexedTools.has(nativeToolName)) {
+                consecutiveIndexedToolCalls[nativeToolName] = (consecutiveIndexedToolCalls[nativeToolName] ?? 0) + 1;
+                if (consecutiveIndexedToolCalls[nativeToolName] >= input.reprofileConsecutiveIndexedCalls) {
+                    pendingReprofile = true;
+                }
+            }
+            else {
+                for (const toolName of Object.keys(consecutiveIndexedToolCalls)) {
+                    consecutiveIndexedToolCalls[toolName] = 0;
+                }
+            }
+            await input.overlayStore.save({ sessionId: input.sessionId, serverId }, {
+                ...overlay,
+                mode: "expanded",
+                activeTools: [...new Set([...overlay.activeTools, nativeToolName])],
+                pendingReprofile,
+                counters: { consecutiveIndexedToolCalls },
+                updatedAt: record.now,
+            });
+            return true;
+        },
+    };
+}
+async function discoverRuntimeMcpDynamicTools(manifest, executor, mcpPlusRuntime) {
     const profiles = buildMcpServerProfilesFromManifest(manifest);
     if (profiles.length === 0 || executor.mcp?.listTools === undefined)
         return [];
@@ -359,7 +597,8 @@ async function discoverRuntimeMcpDynamicTools(manifest, executor) {
             .map(normalizeMcpNativeToolDeclaration)
             .filter((tool) => tool !== undefined);
     }
-    return planMcpHarnessExposure(manifest, inventory).servers.flatMap((server) => [...server.dynamicToolSpecs]);
+    await mcpPlusRuntime?.setNativeInventory(inventory);
+    return planMcpHarnessExposure(manifest, inventory, await mcpPlusRuntime?.exposureStateByServerId(manifest) ?? {}, await mcpPlusRuntime?.learnedProfilesByServerId(manifest) ?? {}).servers.flatMap((server) => [...server.dynamicToolSpecs]);
 }
 function providerToolMappings(manifest) {
     return createProviderToolMappings(manifest.harness.tools);
@@ -2562,6 +2801,123 @@ async function executeBaseToolDecision(input) {
     const dynamicRuntimeArguments = isRecord(dynamicToolSpec?.metadata?.runtimeArguments)
         ? dynamicToolSpec.metadata.runtimeArguments
         : undefined;
+    if (dynamicToolSpec?.metadata?.toolProviderKind === "mcp-plus-control") {
+        const serverId = readString(dynamicToolSpec.metadata.serverId);
+        const controlName = readString(dynamicToolSpec.metadata.controlName);
+        if (serverId === undefined || controlName === undefined || input.mcpPlusRuntime === undefined) {
+            const record = {
+                callId: input.toolCallId,
+                toolId: input.toolId,
+                arguments: input.args,
+                ok: false,
+                error: {
+                    code: "MCP_PLUS_CONTROL_UNAVAILABLE",
+                    message: "MCP+ control tool is not available in this runtime.",
+                    publicSafe: true,
+                },
+            };
+            const observation = createObservationMaterial({
+                observationId: `${input.sessionId}:observation:${input.toolCallId}`,
+                source: "baseTool",
+                status: "failed",
+                title: `MCP+ control ${controlName ?? input.toolId}`,
+                summary: "MCP+ control tool is not available.",
+                refs: [input.toolCallId, input.toolId],
+                payload: record.error,
+                metadata: metadataRecord({ toolCallId: input.toolCallId, toolId: input.toolId }),
+            });
+            return {
+                record,
+                observation,
+                events: ["runtime.mcpPlus.control.unavailable"],
+                governance: {
+                    kind: "runtime.execEngine.baseTool.governanceDecision",
+                    toolId: input.toolId,
+                    status: "deny",
+                    risk: "safe",
+                    policyProfile: input.manifest.toolPolicy.profile,
+                    policyMatrixId: input.manifest.toolPolicy.matrixId,
+                    approvalRequired: false,
+                    approvalReason: "MCP+ control tool is not available.",
+                    sandbox: {
+                        sandboxId: input.manifest.sandbox.sandboxId,
+                        profile: input.manifest.sandbox.profile,
+                        providerFamily: input.manifest.sandbox.providerFamily,
+                        isolationLevel: input.manifest.sandbox.isolationLevel,
+                        filesystem: input.manifest.sandbox.filesystem,
+                        network: input.manifest.sandbox.network,
+                        shell: input.manifest.sandbox.shell,
+                        hostObserved: input.manifest.sandbox.profile === "host-observed",
+                        dependencyRefs: input.manifest.sandbox.dependencyRefs ?? [],
+                    },
+                    resourceLimits: input.manifest.sandbox.resourceLimits,
+                    publicSafe: true,
+                    events: ["runtime.mcpPlus.control.unavailable"],
+                    metadata: { toolCallId: input.toolCallId },
+                },
+            };
+        }
+        const controlResult = await input.mcpPlusRuntime.callControlTool({
+            manifest: input.manifest,
+            serverId,
+            controlName,
+            args: input.args,
+            now: input.now(),
+        });
+        const record = {
+            callId: input.toolCallId,
+            toolId: input.toolId,
+            arguments: input.args,
+            ok: controlResult.ok,
+            ...(controlResult.ok ? { output: controlResult.output } : { error: controlResult.error }),
+        };
+        const controlFailureMessage = controlResult.ok ? undefined : controlResult.error?.message ?? "MCP+ control tool failed.";
+        const observation = createObservationMaterial({
+            observationId: `${input.sessionId}:observation:${input.toolCallId}`,
+            source: "baseTool",
+            status: controlResult.ok ? "completed" : "failed",
+            title: `MCP+ control ${controlName}`,
+            summary: controlResult.ok ? "MCP+ control tool completed." : controlFailureMessage ?? "MCP+ control tool failed.",
+            refs: [input.toolCallId, input.toolId],
+            payload: controlResult.ok ? controlResult.output : controlResult.error ?? { code: "MCP_PLUS_CONTROL_FAILED", message: controlFailureMessage, publicSafe: true },
+            metadata: metadataRecord({
+                toolCallId: input.toolCallId,
+                toolId: input.toolId,
+                serverId,
+                controlName,
+                observationStatus: controlResult.ok ? "completed" : "failed",
+            }),
+        });
+        return {
+            record,
+            observation,
+            events: [controlResult.ok ? "runtime.mcpPlus.control.completed" : "runtime.mcpPlus.control.failed"],
+            governance: {
+                kind: "runtime.execEngine.baseTool.governanceDecision",
+                toolId: input.toolId,
+                status: controlResult.ok ? "allow" : "deny",
+                risk: "safe",
+                policyProfile: input.manifest.toolPolicy.profile,
+                policyMatrixId: input.manifest.toolPolicy.matrixId,
+                approvalRequired: false,
+                sandbox: {
+                    sandboxId: input.manifest.sandbox.sandboxId,
+                    profile: input.manifest.sandbox.profile,
+                    providerFamily: input.manifest.sandbox.providerFamily,
+                    isolationLevel: input.manifest.sandbox.isolationLevel,
+                    filesystem: input.manifest.sandbox.filesystem,
+                    network: input.manifest.sandbox.network,
+                    shell: input.manifest.sandbox.shell,
+                    hostObserved: input.manifest.sandbox.profile === "host-observed",
+                    dependencyRefs: input.manifest.sandbox.dependencyRefs ?? [],
+                },
+                resourceLimits: input.manifest.sandbox.resourceLimits,
+                publicSafe: true,
+                events: [controlResult.ok ? "runtime.mcpPlus.control.completed" : "runtime.mcpPlus.control.failed"],
+                metadata: { serverId, controlName },
+            },
+        };
+    }
     if (dynamicRuntimeToolId !== undefined && dynamicRuntimeToolId !== input.toolId) {
         const delegatedArgs = dynamicRuntimeToolId === "mcp.use"
             ? {
@@ -2576,6 +2932,7 @@ async function executeBaseToolDecision(input) {
             ...input,
             toolId: dynamicRuntimeToolId,
             args: delegatedArgs,
+            mcpPlusRuntime: input.mcpPlusRuntime,
         });
         return {
             ...delegated,
@@ -3525,6 +3882,7 @@ export class PraxisRuntimeKernel {
         });
         const dryRun = options.dryRun !== false;
         manifest = withRuntimeMcpModule(manifest, options.mcpModule);
+        const runtimeMcpBaseManifest = manifest;
         const defaultBaseToolPolicy = {
             workspaceRoot: toolWorkspaceRoot,
             allowedRoots: toolAllowedRoots,
@@ -3573,10 +3931,25 @@ export class PraxisRuntimeKernel {
             id: "praxis-runtime-kernel",
             sessionId,
         };
-        manifest = withRuntimeHarnessTools(manifest, await discoverRuntimeMcpDynamicTools(manifest, executor));
+        const mcpPlusRuntime = createRuntimeMcpPlusController({
+            sessionId,
+            projectId: runtimeMcpPlusProjectId({
+                explicit: options.mcpPlus?.projectId,
+                workspaceRoot: toolWorkspaceRoot,
+            }),
+            profileStore: options.mcpPlus?.profileStore ?? createFileMcpPlusProfileStore(path.join(toolWorkspaceRoot, ".rax_workspace", "mcp-plus")),
+            overlayStore: options.mcpPlus?.overlayStore ?? createInMemoryMcpPlusOverlayStore(),
+            skillStore: options.mcpPlus?.skillStore ?? createFileMcpPlusSkillStore(path.join(toolWorkspaceRoot, ".rax_workspace", "mcp-plus")),
+            reprofileConsecutiveIndexedCalls: options.mcpPlus?.reprofileConsecutiveIndexedCalls ?? 6,
+        });
         const maxModelTurns = manifest.harness.loop.maxModelTurns ?? 2;
         const maxToolCalls = manifest.harness.loop.maxToolCalls ?? 4;
-        const toolMappings = providerToolMappings(manifest);
+        let toolMappings = [];
+        async function refreshRuntimeMcpTools(reason) {
+            manifest = withRuntimeHarnessToolLayer(runtimeMcpBaseManifest, await discoverRuntimeMcpDynamicTools(runtimeMcpBaseManifest, executor, mcpPlusRuntime), reason);
+            toolMappings = providerToolMappings(manifest);
+        }
+        await refreshRuntimeMcpTools("session.checkpoint.start");
         const providerFamily = providerToolSchemaFamilyForModel(manifest.model);
         let toolContextSelection = {
             families: normalizedSelection(options.toolContextSelection?.families),
@@ -4758,6 +5131,7 @@ export class PraxisRuntimeKernel {
                     store,
                     approvalResolver: options.approvalResolver,
                     agentReviewResolver: options.agentReviewResolver,
+                    mcpPlusRuntime,
                     preparedSandbox: sandboxPrepared.sandbox,
                     dependencyRuntime: options.baseToolDependencyRuntime,
                     now,
@@ -4770,6 +5144,16 @@ export class PraxisRuntimeKernel {
                 });
                 toolCalls.push(executed.record);
                 observations.push(executed.observation);
+                const mcpPlusToolCallUpdated = await mcpPlusRuntime.recordToolCall({
+                    manifest,
+                    toolId: executed.record.toolId,
+                    ok: executed.record.ok,
+                    now: now(),
+                });
+                if (executed.record.ok && (mcpPlusToolCallUpdated ||
+                    manifest.harness.tools.find((tool) => tool.toolId === executed.record.toolId)?.metadata?.toolProviderKind === "mcp-plus-control")) {
+                    await refreshRuntimeMcpTools("session.checkpoint.after_mcp_tool");
+                }
                 if (invalidatesFileReadCache(executed.record.toolId)) {
                     sameTurnFileReadCache.clear();
                 }

package/dist/runtimeImplementation/runtime.mcpPlane/index.d.ts

@@ -1,4 +1,4 @@
-import { type ExposureState, type McpCompatibleSurface, type McpPlusManifest, type NativeToolDeclaration } from "@praxis-ai/mcp-plus";
+import { type ExposureMode, type ExposureState, type McpCompatibleSurface, type McpPlusManifest, type NativeToolDeclaration } from "@praxis-ai/mcp-plus";
 import type { ToolSpec } from "../runtimeAgentManifest.js";
 import type { McpRuntimeServerProfile } from "../runtime.execEngine/mcpRuntimeAdapter.js";
 export type McpHarnessServerMode = "native" | "mcp-plus";
@@ -74,6 +74,90 @@ export type McpExposurePlanServer = {
 export type McpHarnessExposurePlan = {
     servers: readonly McpExposurePlanServer[];
 };
+export type McpPlusProfileProposal = {
+    serverId: string;
+    pinnedTools?: readonly string[];
+    warmTools?: readonly string[];
+    indexedTools?: readonly string[];
+    alwaysIndexTools?: readonly string[];
+    toolCards?: Readonly<Record<string, {
+        title?: string;
+        summary?: string;
+        keywords?: readonly string[];
+    }>>;
+    skillChapters?: readonly {
+        id: string;
+        title: string;
+        summary: string;
+    }[];
+    rationale?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type McpPlusLearnedProfile = {
+    schemaVersion: "mcp-plus.profile.v1";
+    serverId: string;
+    projectId: string;
+    exposure: NonNullable<McpPlusManifest["exposure"]>;
+    skills?: NonNullable<McpPlusManifest["skills"]>;
+    rationale?: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type McpPlusRuntimeOverlay = {
+    serverId: string;
+    sessionId: string;
+    mode: ExposureMode;
+    activeTools: readonly string[];
+    pendingReprofile?: boolean;
+    counters: {
+        consecutiveIndexedToolCalls: Readonly<Record<string, number>>;
+    };
+    updatedAt: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type McpPlusProfileStoreKey = {
+    serverId: string;
+    projectId: string;
+};
+export type McpPlusOverlayStoreKey = {
+    serverId: string;
+    sessionId: string;
+};
+export type McpPlusProfileStore = {
+    load(key: McpPlusProfileStoreKey): Promise<McpPlusLearnedProfile | undefined>;
+    save(key: McpPlusProfileStoreKey, profile: McpPlusLearnedProfile): Promise<void>;
+};
+export type McpPlusOverlayStore = {
+    load(key: McpPlusOverlayStoreKey): Promise<McpPlusRuntimeOverlay | undefined>;
+    save(key: McpPlusOverlayStoreKey, overlay: McpPlusRuntimeOverlay): Promise<void>;
+};
+export type McpPlusSkillNote = {
+    id: string;
+    serverId: string;
+    projectId: string;
+    chapter: string;
+    title: string;
+    summary: string;
+    whenToUse?: string;
+    do?: readonly string[];
+    why?: string;
+    avoid?: readonly string[];
+    pitfalls?: readonly string[];
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type McpPlusSkillStore = {
+    list(key: McpPlusProfileStoreKey): Promise<readonly McpPlusSkillNote[]>;
+    read(key: McpPlusProfileStoreKey, query: {
+        id?: string;
+        chapter?: string;
+    }): Promise<readonly McpPlusSkillNote[]>;
+    write(key: McpPlusProfileStoreKey, note: Omit<McpPlusSkillNote, "id" | "serverId" | "projectId" | "createdAt" | "updatedAt"> & {
+        id?: string;
+    }): Promise<McpPlusSkillNote>;
+};
 export type McpPlusApplicationServerInput = McpTransportSpec & {
     serverId: string;
     manifest: McpPlusManifest;
@@ -106,9 +190,36 @@ export declare function buildMcpServerProfilesFromManifest(input: {
     };
 }): readonly McpRuntimeServerProfile[];
 export declare function createMcpApplicationStateView(module: McpHarnessModuleSpec | undefined): McpApplicationStateView;
+export declare function createMcpPlusInitToolDeclaration(): NativeToolDeclaration;
+export declare function createMcpPlusReprofileToolDeclaration(): NativeToolDeclaration;
+export declare function createMcpPlusSkillReadToolDeclaration(): NativeToolDeclaration;
+export declare function createMcpPlusSkillWriteToolDeclaration(): NativeToolDeclaration;
+export declare function createMcpPlusFinishToolDeclaration(): NativeToolDeclaration;
+export declare function createInMemoryMcpPlusProfileStore(initial?: readonly McpPlusLearnedProfile[]): McpPlusProfileStore;
+export declare function createInMemoryMcpPlusOverlayStore(initial?: readonly McpPlusRuntimeOverlay[]): McpPlusOverlayStore;
+export declare function createInMemoryMcpPlusSkillStore(initial?: readonly McpPlusSkillNote[]): McpPlusSkillStore;
+export declare function createFileMcpPlusProfileStore(rootDir: string): McpPlusProfileStore;
+export declare function createFileMcpPlusSkillStore(rootDir: string): McpPlusSkillStore;
+export declare function learnedProfileFromProposal(input: {
+    proposal: McpPlusProfileProposal;
+    nativeTools: readonly NativeToolDeclaration[];
+    projectId: string;
+    now: string;
+    existing?: McpPlusLearnedProfile;
+}): {
+    ok: true;
+    profile: McpPlusLearnedProfile;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        publicSafe: true;
+    };
+};
 export declare function planMcpHarnessExposure(manifest: {
     harness: {
         modules: Readonly<Record<string, unknown>>;
     };
-}, nativeToolInventoryByServerId: Readonly<Record<string, readonly NativeToolDeclaration[]>>, stateByServerId?: Readonly<Record<string, Partial<ExposureState>>>): McpHarnessExposurePlan;
+}, nativeToolInventoryByServerId: Readonly<Record<string, readonly NativeToolDeclaration[]>>, stateByServerId?: Readonly<Record<string, Partial<ExposureState>>>, profileByServerId?: Readonly<Record<string, McpPlusLearnedProfile | undefined>>): McpHarnessExposurePlan;
 export {};

package/dist/runtimeImplementation/runtime.mcpPlane/index.js

@@ -3,7 +3,9 @@
  * 核心目的：把标准 MCP server 声明、MCP+ exposure policy、runtime server profile、
  * dynamic harness tools 和 application view 串成一条 OAO 可编译、可检查、可挂载的合同。
  */
-import { compileMcpPlusManifest, lowerExposurePlanToMcpSurface, planExposure, } from "@praxis-ai/mcp-plus";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { compileMcpPlusManifest, createExpandToolDeclaration, lowerExposurePlanToMcpSurface, planExposure, } from "@praxis-ai/mcp-plus";
 export function mcpServer(serverId, input) {
     return {
         ...input,
@@ -102,6 +104,97 @@ export function createMcpApplicationStateView(module) {
 function toolIdPart(value) {
     return value.replace(/[^a-zA-Z0-9_-]+/gu, ".").replace(/^\.+|\.+$/gu, "") || "tool";
 }
+function jsonObjectSchema(properties, required = []) {
+    return {
+        type: "object",
+        properties,
+        required: [...required],
+        additionalProperties: false,
+    };
+}
+export function createMcpPlusInitToolDeclaration() {
+    return {
+        name: "mcp_plus.init",
+        description: "Submit the first MCP+ profile proposal for this standard MCP server after inspecting its full MCP tools/list surface.",
+        inputSchema: profileProposalInputSchema("init"),
+    };
+}
+export function createMcpPlusReprofileToolDeclaration() {
+    return {
+        name: "mcp_plus.reprofile",
+        description: "Submit an updated MCP+ profile proposal for this standard MCP server when runtime usage shows the current profile is stale.",
+        inputSchema: profileProposalInputSchema("reprofile"),
+    };
+}
+export function createMcpPlusSkillReadToolDeclaration() {
+    return {
+        name: "mcp_plus.skill_read",
+        description: "Read server-bound MCP+ skill notes for the current project when a reusable workflow is relevant.",
+        inputSchema: jsonObjectSchema({
+            serverId: { type: "string" },
+            id: { type: "string" },
+            chapter: { type: "string" },
+        }, ["serverId"]),
+    };
+}
+export function createMcpPlusSkillWriteToolDeclaration() {
+    return {
+        name: "mcp_plus.skill_write",
+        description: "Write a concise server-bound MCP+ skill note for the current project after a reusable workflow, pitfall, or difficult MCP usage is discovered.",
+        inputSchema: jsonObjectSchema({
+            serverId: { type: "string" },
+            chapter: { type: "string" },
+            title: { type: "string" },
+            summary: { type: "string" },
+            whenToUse: { type: "string" },
+            do: { type: "array", items: { type: "string" } },
+            why: { type: "string" },
+            avoid: { type: "array", items: { type: "string" } },
+            pitfalls: { type: "array", items: { type: "string" } },
+        }, ["serverId", "chapter", "title", "summary"]),
+    };
+}
+export function createMcpPlusFinishToolDeclaration() {
+    return {
+        name: "mcp_plus.finish",
+        description: "Finish an MCP+ workflow and optionally submit a reusable skill note. Praxis records the note only when the model provides one.",
+        inputSchema: jsonObjectSchema({
+            serverId: { type: "string" },
+            outcome: { type: "string", enum: ["success", "failure", "partial"] },
+            skill: createMcpPlusSkillWriteToolDeclaration().inputSchema,
+        }, ["serverId", "outcome"]),
+    };
+}
+function profileProposalInputSchema(kind) {
+    return jsonObjectSchema({
+        serverId: { type: "string" },
+        pinnedTools: { type: "array", items: { type: "string" } },
+        warmTools: { type: "array", items: { type: "string" } },
+        indexedTools: { type: "array", items: { type: "string" } },
+        alwaysIndexTools: { type: "array", items: { type: "string" } },
+        toolCards: {
+            type: "object",
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    title: { type: "string" },
+                    summary: { type: "string" },
+                    keywords: { type: "array", items: { type: "string" } },
+                },
+                additionalProperties: false,
+            },
+        },
+        skillChapters: {
+            type: "array",
+            items: jsonObjectSchema({
+                id: { type: "string" },
+                title: { type: "string" },
+                summary: { type: "string" },
+            }, ["id", "title", "summary"]),
+        },
+        rationale: { type: "string", description: `${kind} rationale for the host runtime.` },
+    }, ["serverId"]);
+}
 function dynamicToolSpecForNativeTool(serverId, tool) {
     return {
         toolId: `mcp.${toolIdPart(serverId)}.${toolIdPart(tool.name)}`,
@@ -119,16 +212,278 @@ function dynamicToolSpecForNativeTool(serverId, tool) {
         },
     };
 }
+function dynamicToolSpecForMcpPlusControlTool(serverId, tool) {
+    return {
+        toolId: `mcp.${toolIdPart(serverId)}.${toolIdPart(tool.name)}`,
+        family: "mcp",
+        group: serverId,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        metadata: {
+            toolProviderKind: "mcp-plus-control",
+            serverId,
+            controlName: tool.name,
+            source: "runtime.mcpPlane.mcpPlusControlTool",
+        },
+    };
+}
+function isMcpPlusControlToolName(name) {
+    return name.startsWith("mcp_plus.");
+}
 function dynamicToolSpecsForSurface(serverId, surface) {
-    return surface.tools
-        .filter((tool) => tool.name !== "mcp_plus.expand")
-        .map((tool) => dynamicToolSpecForNativeTool(serverId, tool));
+    return surface.tools.map((tool) => isMcpPlusControlToolName(tool.name)
+        ? dynamicToolSpecForMcpPlusControlTool(serverId, tool)
+        : dynamicToolSpecForNativeTool(serverId, tool));
+}
+export function createInMemoryMcpPlusProfileStore(initial = []) {
+    const profiles = new Map(initial.map((profile) => [`${profile.projectId}:${profile.serverId}`, profile]));
+    return {
+        async load(key) {
+            return profiles.get(`${key.projectId}:${key.serverId}`);
+        },
+        async save(key, profile) {
+            profiles.set(`${key.projectId}:${key.serverId}`, profile);
+        },
+    };
+}
+export function createInMemoryMcpPlusOverlayStore(initial = []) {
+    const overlays = new Map(initial.map((overlay) => [`${overlay.sessionId}:${overlay.serverId}`, overlay]));
+    return {
+        async load(key) {
+            return overlays.get(`${key.sessionId}:${key.serverId}`);
+        },
+        async save(key, overlay) {
+            overlays.set(`${key.sessionId}:${key.serverId}`, overlay);
+        },
+    };
+}
+export function createInMemoryMcpPlusSkillStore(initial = []) {
+    const notes = [...initial];
+    return {
+        async list(key) {
+            return notes.filter((note) => note.projectId === key.projectId && note.serverId === key.serverId);
+        },
+        async read(key, query) {
+            return notes.filter((note) => note.projectId === key.projectId &&
+                note.serverId === key.serverId &&
+                (query.id === undefined || note.id === query.id) &&
+                (query.chapter === undefined || note.chapter === query.chapter));
+        },
+        async write(key, note) {
+            const now = new Date().toISOString();
+            const noteId = note.id ?? `${key.serverId}:${note.chapter}:${toolIdPart(note.title).toLowerCase()}`;
+            const existingIndex = notes.findIndex((item) => item.projectId === key.projectId && item.serverId === key.serverId && item.id === noteId);
+            const written = {
+                ...note,
+                id: noteId,
+                serverId: key.serverId,
+                projectId: key.projectId,
+                createdAt: existingIndex === -1 ? now : notes[existingIndex]?.createdAt ?? now,
+                updatedAt: now,
+            };
+            if (existingIndex === -1)
+                notes.push(written);
+            else
+                notes[existingIndex] = written;
+            return written;
+        },
+    };
+}
+async function readJsonFile(filePath, fallback) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+async function writeJsonFile(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
 }
-export function planMcpHarnessExposure(manifest, nativeToolInventoryByServerId, stateByServerId = {}) {
+function storeFilePart(value) {
+    return toolIdPart(value).replace(/\.+/gu, "-").toLowerCase() || "default";
+}
+export function createFileMcpPlusProfileStore(rootDir) {
+    function profilePath(key) {
+        return path.join(rootDir, "profiles", storeFilePart(key.projectId), `${storeFilePart(key.serverId)}.json`);
+    }
+    return {
+        async load(key) {
+            return await readJsonFile(profilePath(key), undefined);
+        },
+        async save(key, profile) {
+            await writeJsonFile(profilePath(key), profile);
+        },
+    };
+}
+export function createFileMcpPlusSkillStore(rootDir) {
+    function skillPath(key) {
+        return path.join(rootDir, "skills", storeFilePart(key.projectId), `${storeFilePart(key.serverId)}.json`);
+    }
+    return {
+        async list(key) {
+            return await readJsonFile(skillPath(key), []);
+        },
+        async read(key, query) {
+            const notes = await readJsonFile(skillPath(key), []);
+            return notes.filter((note) => (query.id === undefined || note.id === query.id) &&
+                (query.chapter === undefined || note.chapter === query.chapter));
+        },
+        async write(key, note) {
+            const notes = await readJsonFile(skillPath(key), []);
+            const now = new Date().toISOString();
+            const noteId = note.id ?? `${key.serverId}:${note.chapter}:${toolIdPart(note.title).toLowerCase()}`;
+            const existingIndex = notes.findIndex((item) => item.id === noteId);
+            const written = {
+                ...note,
+                id: noteId,
+                serverId: key.serverId,
+                projectId: key.projectId,
+                createdAt: existingIndex === -1 ? now : notes[existingIndex]?.createdAt ?? now,
+                updatedAt: now,
+            };
+            if (existingIndex === -1)
+                notes.push(written);
+            else
+                notes[existingIndex] = written;
+            await writeJsonFile(skillPath(key), notes);
+            return written;
+        },
+    };
+}
+function uniqueStrings(values) {
+    return [...new Set((values ?? []).filter((value) => typeof value === "string" && value.trim().length > 0).map((value) => value.trim()))];
+}
+function defaultToolCard(tool) {
+    return {
+        title: tool.name,
+        summary: tool.description || tool.name,
+        keywords: tool.name.split(/[^a-zA-Z0-9]+/u).filter(Boolean),
+    };
+}
+function learnedManifestFromProfile(profile, server) {
+    return {
+        server: {
+            id: server.serverId,
+            title: server.title ?? server.serverId,
+            summary: server.summary ?? server.manifest?.server.summary ?? "Learned MCP+ profile.",
+        },
+        exposure: profile.exposure,
+        skills: profile.skills,
+    };
+}
+function fallbackMcpPlusManifest(server, nativeTools) {
+    const smallServer = nativeTools.length <= 8;
+    return {
+        server: {
+            id: server.serverId,
+            title: server.title ?? server.serverId,
+            summary: server.summary ?? "Standard MCP server with Praxis MCP+ native exposure.",
+        },
+        exposure: smallServer
+            ? { pinnedTools: nativeTools.map((tool) => tool.name), indexedTools: [] }
+            : {
+                pinnedTools: nativeTools.slice(0, 3).map((tool) => tool.name),
+                indexedTools: nativeTools.slice(3).map((tool) => tool.name),
+                toolCards: Object.fromEntries(nativeTools.slice(3).map((tool) => [tool.name, defaultToolCard(tool)])),
+            },
+    };
+}
+function bootstrapSurface(server, nativeTools) {
+    return {
+        tools: [
+            ...nativeTools,
+            createMcpPlusInitToolDeclaration(),
+            createMcpPlusSkillReadToolDeclaration(),
+            createMcpPlusSkillWriteToolDeclaration(),
+            createMcpPlusFinishToolDeclaration(),
+        ],
+        sidecar: {
+            serverCard: {
+                id: server.serverId,
+                title: server.title ?? server.serverId,
+                summary: server.summary ?? "Standard MCP server awaiting MCP+ profile initialization.",
+                mode: "expanded",
+            },
+            toolIndex: [],
+            skillIndex: [],
+        },
+    };
+}
+export function learnedProfileFromProposal(input) {
+    if (Object.hasOwn(input.proposal, "modeHint")) {
+        return {
+            ok: false,
+            error: {
+                code: "MCP_PLUS_PROFILE_MODE_HINT_UNSUPPORTED",
+                message: "MCP+ profile proposals do not accept modeHint in v1; runtime overlays own exposure mode.",
+                publicSafe: true,
+            },
+        };
+    }
+    const nativeToolNames = new Set(input.nativeTools.map((tool) => tool.name));
+    const referenced = [
+        ...uniqueStrings(input.proposal.pinnedTools),
+        ...uniqueStrings(input.proposal.warmTools),
+        ...uniqueStrings(input.proposal.indexedTools),
+        ...uniqueStrings(input.proposal.alwaysIndexTools),
+        ...Object.keys(input.proposal.toolCards ?? {}),
+    ];
+    const unknown = referenced.filter((toolName) => !nativeToolNames.has(toolName));
+    if (unknown.length > 0) {
+        return {
+            ok: false,
+            error: {
+                code: "MCP_PLUS_PROFILE_UNKNOWN_TOOL",
+                message: `MCP+ profile proposal references unknown tool(s): ${unknown.join(", ")}`,
+                publicSafe: true,
+            },
+        };
+    }
+    const alwaysIndex = new Set(uniqueStrings(input.proposal.alwaysIndexTools));
+    const pinnedAlwaysIndex = uniqueStrings(input.proposal.pinnedTools).filter((toolName) => alwaysIndex.has(toolName));
+    if (pinnedAlwaysIndex.length > 0) {
+        return {
+            ok: false,
+            error: {
+                code: "MCP_PLUS_PROFILE_ALWAYS_INDEX_PINNED",
+                message: `alwaysIndexTools cannot be pinned: ${pinnedAlwaysIndex.join(", ")}`,
+                publicSafe: true,
+            },
+        };
+    }
+    const profile = {
+        schemaVersion: "mcp-plus.profile.v1",
+        serverId: input.proposal.serverId,
+        projectId: input.projectId,
+        exposure: {
+            pinnedTools: uniqueStrings(input.proposal.pinnedTools),
+            warmTools: uniqueStrings(input.proposal.warmTools),
+            indexedTools: uniqueStrings(input.proposal.indexedTools),
+            alwaysIndexTools: uniqueStrings(input.proposal.alwaysIndexTools),
+            toolCards: input.proposal.toolCards === undefined ? undefined : Object.fromEntries(Object.entries(input.proposal.toolCards).map(([toolName, card]) => [toolName, {
+                    title: card.title,
+                    summary: card.summary,
+                    keywords: card.keywords === undefined ? undefined : [...card.keywords],
+                }])),
+        },
+        skills: input.proposal.skillChapters === undefined ? input.existing?.skills : {
+            ...(input.existing?.skills ?? {}),
+            chapters: input.proposal.skillChapters.map((chapter) => ({ ...chapter })),
+        },
+        rationale: input.proposal.rationale,
+        createdAt: input.existing?.createdAt ?? input.now,
+        updatedAt: input.now,
+        metadata: input.proposal.metadata,
+    };
+    return { ok: true, profile };
+}
+export function planMcpHarnessExposure(manifest, nativeToolInventoryByServerId, stateByServerId = {}, profileByServerId = {}) {
     const module = mcpHarnessModuleFrom(manifest.harness);
     const servers = (module?.servers ?? []).map((server) => {
         const nativeTools = [...(nativeToolInventoryByServerId[server.serverId] ?? [])];
-        if (server.mode !== "mcp-plus" || server.manifest === undefined) {
+        if (server.mode !== "mcp-plus") {
             const surface = {
                 tools: nativeTools,
                 sidecar: {
@@ -149,18 +504,45 @@ export function planMcpHarnessExposure(manifest, nativeToolInventoryByServerId,
                 dynamicToolSpecs: nativeTools.map((tool) => dynamicToolSpecForNativeTool(server.serverId, tool)),
             };
         }
-        const graph = compileMcpPlusManifest(server.manifest, nativeTools);
+        const learnedProfile = profileByServerId[server.serverId];
+        if (server.manifest === undefined && learnedProfile === undefined) {
+            const surface = bootstrapSurface(server, nativeTools);
+            return {
+                serverId: server.serverId,
+                mode: "mcp-plus",
+                surface,
+                dynamicToolSpecs: dynamicToolSpecsForSurface(server.serverId, surface),
+            };
+        }
+        const effectiveManifest = server.manifest ?? (learnedProfile === undefined
+            ? fallbackMcpPlusManifest(server, nativeTools)
+            : learnedManifestFromProfile(learnedProfile, server));
+        const graph = compileMcpPlusManifest(effectiveManifest, nativeTools);
         const state = {
             serverId: server.serverId,
             mode: stateByServerId[server.serverId]?.mode ?? "expanded",
             activeTools: stateByServerId[server.serverId]?.activeTools ?? [],
         };
-        const surface = lowerExposurePlanToMcpSurface(planExposure(graph, state));
+        const plan = planExposure(graph, state);
+        const surface = lowerExposurePlanToMcpSurface(plan);
+        const withNativeControls = {
+            tools: [
+                ...surface.tools.filter((tool) => tool.name !== "mcp_plus.expand"),
+                createExpandToolDeclaration(),
+                ...(stateByServerId[server.serverId]?.mode === "frozen" ? [] : [
+                    createMcpPlusSkillReadToolDeclaration(),
+                    createMcpPlusSkillWriteToolDeclaration(),
+                    createMcpPlusFinishToolDeclaration(),
+                ]),
+                ...(stateByServerId[server.serverId]?.activeTools?.includes("mcp_plus.reprofile") ? [createMcpPlusReprofileToolDeclaration()] : []),
+            ],
+            sidecar: surface.sidecar,
+        };
         return {
             serverId: server.serverId,
             mode: "mcp-plus",
-            surface,
-            dynamicToolSpecs: dynamicToolSpecsForSurface(server.serverId, surface),
+            surface: withNativeControls,
+            dynamicToolSpecs: dynamicToolSpecsForSurface(server.serverId, withNativeControls),
         };
     });
     return { servers };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxis-ai/praxis",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "description": "Praxis agentCore architecture scaffold, tests, and engineering contracts.",