@praxis-ai/praxis 0.1.4 → 0.1.6

package/dist/runtimeImplementation/runtime.execEngine/promptContextAssembly.d.ts

@@ -36,6 +36,8 @@ export type PromptContextAssemblyRequest = {
     sessionSummary?: PromptContextSessionSummary;
     conversationWindow?: readonly PromptContextConversationMessage[];
     projectContextGovernanceMaterials?: readonly PromptPackMaterialDraft[];
+    toolDeclarationPreludeMaterials?: readonly PromptPackMaterialDraft[];
+    skillIndexMaterials?: readonly PromptPackMaterialDraft[];
     budget?: PromptContextAssemblyBudget;
     toolContextSelection?: BaseToolContextSelection;
     toolContextUsage?: readonly BaseToolContextUsageRecord[];

package/dist/runtimeImplementation/runtime.execEngine/promptContextAssembly.js

@@ -418,6 +418,37 @@ export function assemblePromptContextMaterials(input) {
         sandboxMode: input.manifest.sandbox?.profile,
         toolSpecificGuidance: PRAXIS_BASE_TOOL_CALLING_PROTOCOL,
     });
+    const toolDeclarationPreludeMaterials = (input.toolDeclarationPreludeMaterials ?? []).map((material, index) => ({
+        ...material,
+        id: material.id ?? `runtime:tool-declaration-prelude:${index + 1}`,
+        kind: material.kind,
+        source: material.source ?? "runtime.toolDeclarationPrelude",
+        sourceCategory: material.sourceCategory ?? "declared-built-in",
+        priority: material.priority ?? 95.5 - index,
+        trusted: material.trusted ?? true,
+        scope: material.scope ?? "runtime.toolCalling",
+        promptSegmentKind: "toolDeclarations",
+        metadata: {
+            ...(material.metadata ?? {}),
+            promptSegmentKind: "toolDeclarations",
+            toolMaterialType: "policy",
+        },
+    }));
+    const skillIndexMaterials = (input.skillIndexMaterials ?? []).map((material, index) => ({
+        ...material,
+        id: material.id ?? `runtime:skill-index:${index + 1}`,
+        kind: material.kind,
+        source: material.source ?? "runtime.skillPlane.index",
+        sourceCategory: material.sourceCategory ?? "declared-built-in",
+        priority: material.priority ?? 94 - index,
+        trusted: material.trusted ?? true,
+        scope: material.scope ?? "runtime.skillPlane.index",
+        promptSegmentKind: "skillIndex",
+        metadata: {
+            ...(material.metadata ?? {}),
+            promptSegmentKind: "skillIndex",
+        },
+    }));
     const sessionSummaryMaterial = input.sessionSummary === undefined
         ? []
         : [{
@@ -445,6 +476,8 @@ export function assemblePromptContextMaterials(input) {
         ...projectContextGovernanceMaterials,
         ...sessionSummaryMaterial,
         ...memoryContextMaterials,
+        ...toolDeclarationPreludeMaterials,
+        ...skillIndexMaterials,
         {
             id: `task:${input.turnIndex}`,
             kind: "user",
@@ -526,6 +559,8 @@ export function assemblePromptContextMaterials(input) {
             ...manifestPromptMaterials,
             declaredRuntimeContextMaterial,
             toolDeclarationsMaterial,
+            ...toolDeclarationPreludeMaterials,
+            ...skillIndexMaterials,
             ...projectContextGovernanceMaterials,
             ...sessionSummaryMaterial,
             ...memoryContextMaterials,

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

@@ -90,7 +90,7 @@ export type McpPlusProfileProposal = {
         title: string;
         summary: string;
     }[];
-    rationale?: string;
+    rationale?: string | Readonly<Record<string, string>>;
     metadata?: Readonly<Record<string, unknown>>;
 };
 export type McpPlusLearnedProfile = {
@@ -99,7 +99,7 @@ export type McpPlusLearnedProfile = {
     projectId: string;
     exposure: NonNullable<McpPlusManifest["exposure"]>;
     skills?: NonNullable<McpPlusManifest["skills"]>;
-    rationale?: string;
+    rationale?: string | Readonly<Record<string, string>>;
     createdAt: string;
     updatedAt: string;
     metadata?: Readonly<Record<string, unknown>>;
@@ -107,14 +107,26 @@ export type McpPlusLearnedProfile = {
 export type McpPlusRuntimeOverlay = {
     serverId: string;
     sessionId: string;
-    mode: ExposureMode;
-    activeTools: readonly string[];
-    pendingReprofile?: boolean;
-    counters: {
-        consecutiveIndexedToolCalls: Readonly<Record<string, number>>;
+    state: {
+        mode: ExposureMode;
+        activeTools: readonly string[];
+        pendingReprofile?: boolean;
+        counters: {
+            consecutiveIndexedToolCalls: Readonly<Record<string, number>>;
+        };
     };
     updatedAt: string;
     metadata?: Readonly<Record<string, unknown>>;
+    /** @deprecated Read-only migration support for pre-contract Praxis overlays. */
+    mode?: ExposureMode;
+    /** @deprecated Read-only migration support for pre-contract Praxis overlays. */
+    activeTools?: readonly string[];
+    /** @deprecated Read-only migration support for pre-contract Praxis overlays. */
+    pendingReprofile?: boolean;
+    /** @deprecated Read-only migration support for pre-contract Praxis overlays. */
+    counters?: {
+        consecutiveIndexedToolCalls: Readonly<Record<string, number>>;
+    };
 };
 export type McpPlusProfileStoreKey = {
     serverId: string;
@@ -206,6 +218,7 @@ export declare function learnedProfileFromProposal(input: {
     projectId: string;
     now: string;
     existing?: McpPlusLearnedProfile;
+    protectedAlwaysIndexTools?: readonly string[];
 }): {
     ok: true;
     profile: McpPlusLearnedProfile;

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

@@ -5,7 +5,7 @@
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { compileMcpPlusManifest, createExpandToolDeclaration, lowerExposurePlanToMcpSurface, planExposure, } from "@praxis-ai/mcp-plus";
+import { compileMcpPlusManifest, createExpandToolDeclaration, createInitToolDeclaration as createMcpPlusContractInitToolDeclaration, createLearnedProfileFromProposal as createContractLearnedProfileFromProposal, createReprofileToolDeclaration as createMcpPlusContractReprofileToolDeclaration, lowerExposurePlanToMcpSurface, mergeMcpPlusPolicy, normalizeProfileProposal, planExposure, validateProfileProposal, } from "@praxis-ai/mcp-plus";
 export function mcpServer(serverId, input) {
     return {
         ...input,
@@ -42,6 +42,14 @@ export const mcp = {
                 toolId: "mcp.resources",
                 metadata: { source: "praxis.mcp.recommendedTools", toolProviderKind: "mcp-static" },
             },
+            {
+                toolId: "mcp.prompts",
+                metadata: { source: "praxis.mcp.recommendedTools", toolProviderKind: "mcp-static" },
+            },
+            {
+                toolId: "mcp.completions",
+                metadata: { source: "praxis.mcp.recommendedTools", toolProviderKind: "mcp-static" },
+            },
         ];
     },
 };
@@ -113,18 +121,10 @@ function jsonObjectSchema(properties, required = []) {
     };
 }
 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"),
-    };
+    return createMcpPlusContractInitToolDeclaration();
 }
 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"),
-    };
+    return createMcpPlusContractReprofileToolDeclaration();
 }
 export function createMcpPlusSkillReadToolDeclaration() {
     return {
@@ -165,36 +165,6 @@ export function createMcpPlusFinishToolDeclaration() {
         }, ["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)}`,
@@ -362,6 +332,47 @@ function defaultToolCard(tool) {
         keywords: tool.name.split(/[^a-zA-Z0-9]+/u).filter(Boolean),
     };
 }
+function profileRationaleForContract(rationale) {
+    if (typeof rationale === "string") {
+        return rationale.trim().length === 0 ? undefined : { summary: rationale };
+    }
+    if (rationale === undefined)
+        return undefined;
+    return Object.fromEntries(Object.entries(rationale).filter(([, value]) => typeof value === "string"));
+}
+function toContractProfileProposal(proposal) {
+    const toolCards = Object.fromEntries(Object.entries(proposal.toolCards ?? {}).map(([toolName, card]) => [toolName, {
+            title: card.title,
+            summary: card.summary,
+            keywords: card.keywords === undefined ? undefined : [...card.keywords],
+        }]));
+    const contractProposal = {
+        serverId: proposal.serverId,
+        pinnedTools: uniqueStrings(proposal.pinnedTools),
+        warmTools: proposal.warmTools === undefined ? undefined : uniqueStrings(proposal.warmTools),
+        indexedTools: uniqueStrings(proposal.indexedTools),
+        alwaysIndexTools: proposal.alwaysIndexTools === undefined ? undefined : uniqueStrings(proposal.alwaysIndexTools),
+        toolCards,
+        skillChapters: proposal.skillChapters?.map((chapter) => ({ ...chapter })),
+        rationale: profileRationaleForContract(proposal.rationale),
+    };
+    if (Object.hasOwn(proposal, "modeHint")) {
+        contractProposal.modeHint = proposal.modeHint;
+    }
+    return Object.fromEntries(Object.entries(contractProposal).filter(([, value]) => value !== undefined));
+}
+function profileErrorCodeFromValidationIssue(code) {
+    switch (code) {
+        case "unknown_tool":
+            return "MCP_PLUS_PROFILE_UNKNOWN_TOOL";
+        case "always_index_pinned":
+            return "MCP_PLUS_PROFILE_ALWAYS_INDEX_PINNED";
+        case "reserved_runtime_field":
+            return "MCP_PLUS_PROFILE_MODE_HINT_UNSUPPORTED";
+        default:
+            return "MCP_PLUS_PROFILE_INVALID_PROPOSAL";
+    }
+}
 function learnedManifestFromProfile(profile, server) {
     return {
         server: {
@@ -373,6 +384,28 @@ function learnedManifestFromProfile(profile, server) {
         skills: profile.skills,
     };
 }
+function contractLearnedProfileFromPraxisProfile(profile) {
+    const toolCards = Object.fromEntries(Object.entries(profile.exposure.toolCards ?? {}).flatMap(([toolName, card]) => {
+        if (typeof card.summary !== "string" || card.summary.trim().length === 0)
+            return [];
+        return [[toolName, {
+                    title: card.title,
+                    summary: card.summary,
+                    keywords: card.keywords === undefined ? undefined : [...card.keywords],
+                }]];
+    }));
+    return {
+        schemaVersion: profile.schemaVersion,
+        serverId: profile.serverId,
+        pinnedTools: [...(profile.exposure.pinnedTools ?? [])],
+        warmTools: [...(profile.exposure.warmTools ?? [])],
+        indexedTools: [...(profile.exposure.indexedTools ?? [])],
+        alwaysIndexTools: [...(profile.exposure.alwaysIndexTools ?? [])],
+        toolCards,
+        skillChapters: profile.skills?.chapters?.map((chapter) => ({ ...chapter })),
+        rationale: profileRationaleForContract(profile.rationale),
+    };
+}
 function fallbackMcpPlusManifest(server, nativeTools) {
     const smallServer = nativeTools.length <= 8;
     return {
@@ -412,65 +445,41 @@ function bootstrapSurface(server, nativeTools) {
     };
 }
 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) {
+    const contractProposal = toContractProfileProposal(input.proposal);
+    const validation = validateProfileProposal(contractProposal, input.nativeTools, {
+        serverId: input.proposal.serverId,
+        alwaysIndexTools: [
+            ...(input.existing?.exposure.alwaysIndexTools ?? []),
+            ...(input.protectedAlwaysIndexTools ?? []),
+        ],
+    });
+    if (!validation.valid) {
+        const primary = validation.issues[0];
         return {
             ok: false,
             error: {
-                code: "MCP_PLUS_PROFILE_ALWAYS_INDEX_PINNED",
-                message: `alwaysIndexTools cannot be pinned: ${pinnedAlwaysIndex.join(", ")}`,
+                code: primary === undefined ? "MCP_PLUS_PROFILE_INVALID_PROPOSAL" : profileErrorCodeFromValidationIssue(primary.code),
+                message: validation.issues.map((issue) => issue.message).join(" "),
                 publicSafe: true,
             },
         };
     }
+    const normalizedProposal = normalizeProfileProposal(contractProposal);
+    const contractProfile = createContractLearnedProfileFromProposal(normalizedProposal);
     const profile = {
         schemaVersion: "mcp-plus.profile.v1",
-        serverId: input.proposal.serverId,
+        serverId: contractProfile.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],
-                }])),
+            pinnedTools: contractProfile.pinnedTools ?? [],
+            warmTools: contractProfile.warmTools ?? [],
+            indexedTools: contractProfile.indexedTools ?? [],
+            alwaysIndexTools: contractProfile.alwaysIndexTools ?? [],
+            toolCards: contractProfile.toolCards,
         },
-        skills: input.proposal.skillChapters === undefined ? input.existing?.skills : {
+        skills: contractProfile.skillChapters === undefined ? input.existing?.skills : {
             ...(input.existing?.skills ?? {}),
-            chapters: input.proposal.skillChapters.map((chapter) => ({ ...chapter })),
+            chapters: contractProfile.skillChapters.map((chapter) => ({ ...chapter })),
         },
         rationale: input.proposal.rationale,
         createdAt: input.existing?.createdAt ?? input.now,
@@ -514,9 +523,15 @@ export function planMcpHarnessExposure(manifest, nativeToolInventoryByServerId,
                 dynamicToolSpecs: dynamicToolSpecsForSurface(server.serverId, surface),
             };
         }
-        const effectiveManifest = server.manifest ?? (learnedProfile === undefined
+        const baseManifest = server.manifest ?? (learnedProfile === undefined
             ? fallbackMcpPlusManifest(server, nativeTools)
             : learnedManifestFromProfile(learnedProfile, server));
+        const effectiveManifest = learnedProfile === undefined
+            ? baseManifest
+            : mergeMcpPlusPolicy({
+                manifest: baseManifest,
+                learnedProfile: contractLearnedProfileFromPraxisProfile(learnedProfile),
+            });
         const graph = compileMcpPlusManifest(effectiveManifest, nativeTools);
         const state = {
             serverId: server.serverId,
@@ -525,10 +540,11 @@ export function planMcpHarnessExposure(manifest, nativeToolInventoryByServerId,
         };
         const plan = planExposure(graph, state);
         const surface = lowerExposurePlanToMcpSurface(plan);
+        const shouldExposeExpandControl = state.mode === "frozen" || surface.sidecar.toolIndex.length > 0;
         const withNativeControls = {
             tools: [
                 ...surface.tools.filter((tool) => tool.name !== "mcp_plus.expand"),
-                createExpandToolDeclaration(),
+                ...(shouldExposeExpandControl ? [createExpandToolDeclaration()] : []),
                 ...(stateByServerId[server.serverId]?.mode === "frozen" ? [] : [
                     createMcpPlusSkillReadToolDeclaration(),
                     createMcpPlusSkillWriteToolDeclaration(),

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

@@ -0,0 +1,119 @@
+import type { PromptPackMaterialDraft } from "../../executionEngine/promptPack/promptDefiner.js";
+export type SkillPlaneScope = "agent" | "project" | "workspace" | "user" | "session";
+export type SkillPlanePromotionState = "experience" | "skill" | "candidate-mcp-plus" | "mcp-plus" | "tool";
+export type SkillHead = {
+    skillId: string;
+    title: string;
+    summary: string;
+    scope?: SkillPlaneScope;
+    whenToUse?: string;
+    why?: string;
+    keywords?: readonly string[];
+    pitfallsPreview?: readonly string[];
+    bodyRef?: string;
+    promotedFrom?: readonly string[];
+    promotionState?: SkillPlanePromotionState;
+};
+export type SkillBody = SkillHead & {
+    prerequisites?: readonly string[];
+    do?: readonly string[];
+    avoid?: readonly string[];
+    pitfalls?: readonly string[];
+    verification?: readonly string[];
+    examples?: readonly string[];
+    promotionSignals?: readonly string[];
+    updatedAt: string;
+};
+export type SkillSourceSpec = {
+    kind: "directory";
+    path: string;
+    scope?: SkillPlaneScope;
+} | {
+    kind: "package";
+    packageName: string;
+    scope?: SkillPlaneScope;
+} | {
+    kind: "inline";
+    heads: readonly SkillHead[];
+};
+export type SkillPlaneIndexPolicy = {
+    maxHeads: number;
+    includeScopes: readonly SkillPlaneScope[];
+};
+export type SkillPlaneBodyLoadPolicy = {
+    mode: "on-demand" | "eager" | "disabled";
+    maxBodiesPerTurn: number;
+};
+export type SkillPlaneLifecyclePolicy = {
+    allowWrite: boolean;
+    checkpointWrites: boolean;
+    promotion: "off" | "suggest" | "auto";
+};
+export type SkillPlaneModuleSpec = {
+    kind: "praxis.skill.module";
+    version: "praxis.skill.v1";
+    sources: readonly SkillSourceSpec[];
+    indexPolicy: SkillPlaneIndexPolicy;
+    bodyLoadPolicy: SkillPlaneBodyLoadPolicy;
+    lifecycle: SkillPlaneLifecyclePolicy;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type SkillPlaneListHeadsQuery = {
+    scopes?: readonly SkillPlaneScope[];
+};
+export type SkillPlaneStore = {
+    listHeads(query?: SkillPlaneListHeadsQuery): Promise<readonly SkillHead[]>;
+    readBody(skillId: string): Promise<SkillBody | undefined>;
+    write(body: SkillBody): Promise<SkillBody>;
+};
+export type SkillPlaneSourceResolutionInput = {
+    workspaceRoot?: string;
+};
+export type SkillWriteProposal = {
+    kind: "praxis.skill.writeProposal";
+    body: SkillBody;
+    reason?: string;
+    safeForRuntimeInspection: true;
+};
+export type SkillPromotionAdvice = {
+    kind: "praxis.skill.promotionAdvice";
+    skillId: string;
+    from?: SkillPlanePromotionState;
+    target: "candidate-mcp-plus";
+    autoGenerateTool: false;
+    reason?: string;
+    signals?: readonly string[];
+};
+export declare const skill: {
+    readonly directory: (directoryPath: string, input?: {
+        scope?: SkillPlaneScope;
+    }) => SkillSourceSpec;
+    readonly package: (packageName: string, input?: {
+        scope?: SkillPlaneScope;
+    }) => SkillSourceSpec;
+    readonly inline: (heads: readonly SkillHead[]) => SkillSourceSpec;
+    readonly module: (input?: {
+        sources?: readonly SkillSourceSpec[];
+        indexPolicy?: Partial<SkillPlaneIndexPolicy>;
+        bodyLoadPolicy?: Partial<SkillPlaneBodyLoadPolicy>;
+        lifecycle?: Partial<SkillPlaneLifecyclePolicy>;
+        metadata?: Readonly<Record<string, unknown>>;
+    }) => SkillPlaneModuleSpec;
+};
+export declare function isSkillPlaneModuleSpec(value: unknown): value is SkillPlaneModuleSpec;
+export declare function skillPlaneModuleFrom(input: {
+    modules?: Readonly<Record<string, unknown>>;
+}): SkillPlaneModuleSpec | undefined;
+export declare function runtimeRequirementsForSkillModule(module: SkillPlaneModuleSpec | undefined): readonly string[];
+export declare function loadSkillHeadsFromSource(source: SkillSourceSpec, input?: SkillPlaneSourceResolutionInput): Promise<readonly SkillHead[]>;
+export declare function loadSkillHeadsFromSources(sources: readonly SkillSourceSpec[], input?: SkillPlaneSourceResolutionInput): Promise<readonly SkillHead[]>;
+export declare function createInMemorySkillPlaneStore(initialBodies?: readonly SkillBody[]): SkillPlaneStore;
+export declare function createFileSkillPlaneStore(rootDir: string): SkillPlaneStore;
+export declare function renderSkillIndexMaterial(heads: readonly SkillHead[]): PromptPackMaterialDraft;
+export declare function createSkillWriteProposal(body: SkillBody, input?: {
+    reason?: string;
+}): SkillWriteProposal;
+export declare function adviseSkillPromotion(skillHead: SkillHead, input?: {
+    reason?: string;
+    signals?: readonly string[];
+}): SkillPromotionAdvice;