@praxis-ai/praxis 0.1.4 → 0.1.6

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

@@ -0,0 +1,274 @@
+/*
+ * 文件定位：Runtime Skill Plane / 技能索引与按需正文加载合约。
+ * 核心目的：让 Praxis runtime 能声明、索引、读取和写入可复用技能经验，
+ * 但不把技能直接降级成工具声明或外部服务配置。
+ */
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+const DEFAULT_INDEX_POLICY = {
+    maxHeads: 40,
+    includeScopes: ["agent", "project", "workspace"],
+};
+const DEFAULT_BODY_LOAD_POLICY = {
+    mode: "on-demand",
+    maxBodiesPerTurn: 3,
+};
+const DEFAULT_LIFECYCLE_POLICY = {
+    allowWrite: true,
+    checkpointWrites: true,
+    promotion: "suggest",
+};
+export const skill = {
+    directory(directoryPath, input) {
+        return input === undefined
+            ? { kind: "directory", path: directoryPath }
+            : { kind: "directory", path: directoryPath, scope: input.scope };
+    },
+    package(packageName, input) {
+        return input === undefined
+            ? { kind: "package", packageName }
+            : { kind: "package", packageName, scope: input.scope };
+    },
+    inline(heads) {
+        return { kind: "inline", heads };
+    },
+    module(input = {}) {
+        return {
+            kind: "praxis.skill.module",
+            version: "praxis.skill.v1",
+            sources: input.sources ?? [],
+            indexPolicy: {
+                ...DEFAULT_INDEX_POLICY,
+                ...input.indexPolicy,
+            },
+            bodyLoadPolicy: {
+                ...DEFAULT_BODY_LOAD_POLICY,
+                ...input.bodyLoadPolicy,
+            },
+            lifecycle: {
+                ...DEFAULT_LIFECYCLE_POLICY,
+                ...input.lifecycle,
+            },
+            metadata: input.metadata,
+        };
+    },
+};
+export function isSkillPlaneModuleSpec(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.kind === "praxis.skill.module" && Array.isArray(record.sources);
+}
+export function skillPlaneModuleFrom(input) {
+    const candidate = input.modules?.skill;
+    return isSkillPlaneModuleSpec(candidate) ? candidate : undefined;
+}
+export function runtimeRequirementsForSkillModule(module) {
+    return module === undefined ? [] : ["runtime.skill"];
+}
+function isSkillHeadLike(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.skillId === "string" && typeof record.title === "string" && typeof record.summary === "string";
+}
+function headsFromUnknown(value) {
+    if (Array.isArray(value))
+        return value.filter(isSkillHeadLike);
+    if (typeof value !== "object" || value === null)
+        return [];
+    const record = value;
+    if (Array.isArray(record.skillHeads))
+        return record.skillHeads.filter(isSkillHeadLike);
+    if (Array.isArray(record.heads))
+        return record.heads.filter(isSkillHeadLike);
+    if (Array.isArray(record.skills))
+        return record.skills.filter(isSkillHeadLike);
+    return isSkillHeadLike(value) ? [value] : [];
+}
+function withSourceScope(heads, scope) {
+    if (scope === undefined)
+        return heads;
+    return heads.map((head) => ({
+        ...head,
+        scope: head.scope ?? scope,
+    }));
+}
+export async function loadSkillHeadsFromSource(source, input = {}) {
+    if (source.kind === "inline")
+        return source.heads;
+    if (source.kind === "package") {
+        const module = await import(source.packageName);
+        return withSourceScope([
+            ...headsFromUnknown(module.skillHeads),
+            ...headsFromUnknown(module.heads),
+            ...headsFromUnknown(module.skills),
+            ...headsFromUnknown(module.default),
+        ], source.scope);
+    }
+    const rootDir = path.isAbsolute(source.path)
+        ? source.path
+        : path.resolve(input.workspaceRoot ?? process.cwd(), source.path);
+    let entries;
+    try {
+        entries = await readdir(rootDir);
+    }
+    catch {
+        return [];
+    }
+    const heads = await Promise.all(entries
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => readJsonFile(path.join(rootDir, entry), undefined).then(headsFromUnknown)));
+    return withSourceScope(heads.flat(), source.scope);
+}
+export async function loadSkillHeadsFromSources(sources, input = {}) {
+    const heads = await Promise.all(sources.map((source) => loadSkillHeadsFromSource(source, input)));
+    return heads.flat();
+}
+function headFromBody(body) {
+    return {
+        skillId: body.skillId,
+        title: body.title,
+        summary: body.summary,
+        scope: body.scope,
+        whenToUse: body.whenToUse,
+        why: body.why,
+        keywords: body.keywords,
+        pitfallsPreview: body.pitfallsPreview,
+        bodyRef: body.bodyRef,
+        promotedFrom: body.promotedFrom,
+        promotionState: body.promotionState,
+    };
+}
+function scopeMatches(head, scopes) {
+    if (scopes === undefined || scopes.length === 0)
+        return true;
+    return head.scope !== undefined && scopes.includes(head.scope);
+}
+function sortHeads(heads) {
+    return [...heads].sort((left, right) => left.skillId.localeCompare(right.skillId));
+}
+export function createInMemorySkillPlaneStore(initialBodies = []) {
+    const bodies = new Map(initialBodies.map((body) => [body.skillId, body]));
+    return {
+        async listHeads(query) {
+            return sortHeads([...bodies.values()].map(headFromBody).filter((head) => scopeMatches(head, query?.scopes)));
+        },
+        async readBody(skillId) {
+            return bodies.get(skillId);
+        },
+        async write(body) {
+            bodies.set(body.skillId, body);
+            return body;
+        },
+    };
+}
+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 });
+}
+function skillFilePart(skillId) {
+    const sanitized = skillId
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/gu, "-")
+        .replace(/^[._-]+|[._-]+$/gu, "")
+        .slice(0, 64)
+        .toLowerCase() || "skill";
+    const stableSuffix = createHash("sha256").update(skillId).digest("hex").slice(0, 16);
+    return `${sanitized}-${stableSuffix}.json`;
+}
+export function createFileSkillPlaneStore(rootDir) {
+    function bodyPath(skillId) {
+        return path.join(rootDir, skillFilePart(skillId));
+    }
+    async function listBodies() {
+        let entries;
+        try {
+            entries = await readdir(rootDir);
+        }
+        catch {
+            return [];
+        }
+        const bodies = await Promise.all(entries
+            .filter((entry) => entry.endsWith(".json"))
+            .map((entry) => readJsonFile(path.join(rootDir, entry), undefined)));
+        return bodies.filter((body) => body !== undefined && typeof body.skillId === "string");
+    }
+    return {
+        async listHeads(query) {
+            return sortHeads((await listBodies()).map(headFromBody).filter((head) => scopeMatches(head, query?.scopes)));
+        },
+        async readBody(skillId) {
+            return await readJsonFile(bodyPath(skillId), undefined);
+        },
+        async write(body) {
+            await writeJsonFile(bodyPath(body.skillId), body);
+            return body;
+        },
+    };
+}
+function compactLine(label, value) {
+    if (value === undefined)
+        return undefined;
+    const rendered = typeof value === "string"
+        ? value.trim()
+        : value.map((item) => item.trim()).filter(Boolean).join(", ");
+    return rendered.length === 0 ? undefined : `${label}: ${rendered}`;
+}
+export function renderSkillIndexMaterial(heads) {
+    const lines = ["# Skill Plane Index"];
+    for (const head of sortHeads(heads)) {
+        lines.push(`- ${head.skillId}: ${head.title}. ${head.summary}`);
+        const detailLines = [
+            compactLine("  scope", head.scope),
+            compactLine("  when", head.whenToUse),
+            compactLine("  why", head.why),
+            compactLine("  keywords", head.keywords),
+            compactLine("  pitfalls preview", head.pitfallsPreview),
+            compactLine("  body ref", head.bodyRef),
+            compactLine("  promotion", head.promotionState),
+        ].filter((line) => line !== undefined);
+        lines.push(...detailLines);
+    }
+    return {
+        id: "runtime:skill-plane:index",
+        kind: "runtime",
+        source: "runtime.skillPlane.index",
+        sourceCategory: "declared-built-in",
+        trusted: true,
+        promptSegmentKind: "skillIndex",
+        metadata: {
+            promptSegmentKind: "skillIndex",
+            generatedBy: "runtime.skillPlane",
+        },
+        text: lines.join("\n"),
+    };
+}
+export function createSkillWriteProposal(body, input = {}) {
+    return {
+        kind: "praxis.skill.writeProposal",
+        body,
+        reason: input.reason,
+        safeForRuntimeInspection: true,
+    };
+}
+export function adviseSkillPromotion(skillHead, input = {}) {
+    return {
+        kind: "praxis.skill.promotionAdvice",
+        skillId: skillHead.skillId,
+        from: skillHead.promotionState,
+        target: "candidate-mcp-plus",
+        autoGenerateTool: false,
+        reason: input.reason,
+        signals: input.signals,
+    };
+}

package/dist/runtimeImplementation/runtimeAgentManifest.js

@@ -12,6 +12,7 @@ import { createBaseToolSupportCatalog } from "./runtime.execEngine/baseToolSuppo
 import { canonicalDependencyId, dependencyKindFromId, } from "./runtime.dependencyPlane/index.js";
 import { capability as capabilityAuthoring, } from "./runtime.provisionPlane/index.js";
 import { mcpHarnessModuleFrom, runtimeRequirementsForMcpModule, } from "./runtime.mcpPlane/index.js";
+import { runtimeRequirementsForSkillModule, skillPlaneModuleFrom, } from "./runtime.skillPlane/index.js";
 export class PromptPack {
     promptPackId;
     base;
@@ -1272,6 +1273,7 @@ function normalizeHarness(input, authoring, normalizedTools) {
         runtimeRequirements: cleanList([
             ...(input.runtimeRequirements ?? []),
             ...runtimeRequirementsForMcpModule(mcpHarnessModuleFrom({ modules: input.modules })),
+            ...runtimeRequirementsForSkillModule(skillPlaneModuleFrom({ modules: input.modules })),
         ]),
         capabilities: authoring.capabilities,
         dependencies: authoring.dependencies,

package/dist/toolBase/catalog.d.ts

@@ -202,6 +202,30 @@ export declare const TOOL_BASE_CATALOG: ({
     aliases: string[];
     capabilityTags: string[];
     requiresRuntimePorts: string[];
+} | {
+    id: "mcp.prompts";
+    title: string;
+    layer: "agent";
+    visibility: "deferred";
+    risk: "read";
+    interaction: "inspect";
+    description: string;
+    inputSchema: Readonly<Record<string, unknown>>;
+    aliases: string[];
+    capabilityTags: string[];
+    requiresRuntimePorts: string[];
+} | {
+    id: "mcp.completions";
+    title: string;
+    layer: "agent";
+    visibility: "deferred";
+    risk: "read";
+    interaction: "inspect";
+    description: string;
+    inputSchema: Readonly<Record<string, unknown>>;
+    aliases: string[];
+    capabilityTags: string[];
+    requiresRuntimePorts: string[];
 } | {
     id: "lsp.query";
     title: string;

package/dist/toolBase/catalog.js

@@ -289,13 +289,51 @@ export const TOOL_BASE_CATALOG = [
         visibility: "deferred",
         risk: "read",
         interaction: "inspect",
-        description: "List or read resources exposed by mounted MCP servers.",
+        description: "List resources, list resource templates, read, subscribe to, or unsubscribe from resources exposed by mounted MCP servers.",
         inputSchema: objectSchema({
             server: { type: "string" },
             uri: { type: "string" },
-            action: { type: "string", enum: ["list", "read"] },
+            subscriptionId: { type: "string" },
+            action: { type: "string", enum: ["list", "templates", "read", "subscribe", "unsubscribe"] },
         }, ["action"]),
-        aliases: ["list_mcp_resources", "read_mcp_resource"],
+        aliases: ["list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource", "subscribe_mcp_resource", "unsubscribe_mcp_resource"],
+        capabilityTags: ["mcp", "external", "context"],
+        requiresRuntimePorts: ["mcp"],
+    },
+    {
+        id: "mcp.prompts",
+        title: "Read MCP Prompts",
+        layer: "agent",
+        visibility: "deferred",
+        risk: "read",
+        interaction: "inspect",
+        description: "List or get prompts exposed by mounted MCP servers.",
+        inputSchema: objectSchema({
+            server: { type: "string" },
+            name: { type: "string" },
+            cursor: { type: "string" },
+            action: { type: "string", enum: ["list", "get"] },
+            arguments: { type: "object" },
+        }, ["action"]),
+        aliases: ["list_mcp_prompts", "get_mcp_prompt"],
+        capabilityTags: ["mcp", "external", "context"],
+        requiresRuntimePorts: ["mcp"],
+    },
+    {
+        id: "mcp.completions",
+        title: "Complete MCP Arguments",
+        layer: "agent",
+        visibility: "deferred",
+        risk: "read",
+        interaction: "inspect",
+        description: "Request completion suggestions for prompt arguments or resource template variables exposed by mounted MCP servers.",
+        inputSchema: objectSchema({
+            server: { type: "string" },
+            ref: { type: "object" },
+            argument: { type: "object" },
+            context: { type: "object" },
+        }, ["ref", "argument"]),
+        aliases: ["complete_mcp_argument", "complete_mcp_resource_template"],
         capabilityTags: ["mcp", "external", "context"],
         requiresRuntimePorts: ["mcp"],
     },

package/dist/toolBase/profiles.d.ts

@@ -1,6 +1,6 @@
 export declare const MINIMAL_CODING_TOOL_IDS: readonly ["shell.run", "file.read", "file.search", "patch.apply", "plan.update", "user.ask"];
 export declare const STANDARD_AGENT_TOOL_IDS: readonly ["shell.run", "file.read", "file.search", "patch.apply", "plan.update", "user.ask", "web.search", "web.fetch", "skill.load", "mcp.use", "agent.spawn"];
-export declare const EXTENDED_AGENT_TOOL_IDS: readonly ["shell.run", "file.read", "file.search", "patch.apply", "plan.update", "user.ask", "web.search", "web.fetch", "skill.load", "mcp.use", "agent.spawn", "file.write", "file.edit", "agent.message", "agent.wait", "context.load", "mcp.resources", "lsp.query", "browser.use", "computer.use", "image.view", "image.generate", "audio.transcribe", "media.generate", "memory.use", "repo.inspect"];
+export declare const EXTENDED_AGENT_TOOL_IDS: readonly ["shell.run", "file.read", "file.search", "patch.apply", "plan.update", "user.ask", "web.search", "web.fetch", "skill.load", "mcp.use", "agent.spawn", "file.write", "file.edit", "agent.message", "agent.wait", "context.load", "mcp.resources", "mcp.prompts", "lsp.query", "browser.use", "computer.use", "image.view", "image.generate", "audio.transcribe", "media.generate", "memory.use", "repo.inspect"];
 export declare const TOOL_BASE_PROFILES: readonly [{
     readonly name: "minimalCoding";
     readonly description: "Pi/Codex-like small coding set for models that perform best with a short familiar tool list.";
@@ -19,9 +19,9 @@ export declare const TOOL_BASE_PROFILES: readonly [{
     readonly name: "extendedAgent";
     readonly description: "Large set for high-capability runtimes; uncommon tools remain deferred until the agent asks for them.";
     readonly defaultVisibility: "deferred";
-    readonly toolIds: readonly ["shell.run", "file.read", "file.search", "patch.apply", "plan.update", "user.ask", "web.search", "web.fetch", "skill.load", "mcp.use", "agent.spawn", "file.write", "file.edit", "agent.message", "agent.wait", "context.load", "mcp.resources", "lsp.query", "browser.use", "computer.use", "image.view", "image.generate", "audio.transcribe", "media.generate", "memory.use", "repo.inspect"];
+    readonly toolIds: readonly ["shell.run", "file.read", "file.search", "patch.apply", "plan.update", "user.ask", "web.search", "web.fetch", "skill.load", "mcp.use", "agent.spawn", "file.write", "file.edit", "agent.message", "agent.wait", "context.load", "mcp.resources", "mcp.prompts", "lsp.query", "browser.use", "computer.use", "image.view", "image.generate", "audio.transcribe", "media.generate", "memory.use", "repo.inspect"];
     readonly hiddenToolIds: readonly [];
-    readonly deferredToolIds: readonly ["file.write", "file.edit", "agent.message", "agent.wait", "context.load", "mcp.resources", "lsp.query", "browser.use", "computer.use", "image.view", "image.generate", "audio.transcribe", "media.generate", "memory.use", "repo.inspect"];
+    readonly deferredToolIds: readonly ["file.write", "file.edit", "agent.message", "agent.wait", "context.load", "mcp.resources", "mcp.prompts", "lsp.query", "browser.use", "computer.use", "image.view", "image.generate", "audio.transcribe", "media.generate", "memory.use", "repo.inspect"];
 }, {
     readonly name: "runtimeOnly";
     readonly description: "Runtime governance ports and internal operations; never sent directly to the model.";

package/dist/toolBase/profiles.js

@@ -22,6 +22,7 @@ export const EXTENDED_AGENT_TOOL_IDS = [
     "agent.wait",
     "context.load",
     "mcp.resources",
+    "mcp.prompts",
     "lsp.query",
     "browser.use",
     "computer.use",
@@ -62,6 +63,7 @@ export const TOOL_BASE_PROFILES = [
             "agent.wait",
             "context.load",
             "mcp.resources",
+            "mcp.prompts",
             "lsp.query",
             "browser.use",
             "computer.use",

package/dist/toolBase/types.d.ts

@@ -3,7 +3,7 @@ export type ToolBaseVisibility = "model" | "deferred" | "runtime" | "disabled";
 export type ToolBaseRisk = "safe" | "read" | "write" | "network" | "execute" | "dangerous";
 export type ToolBaseInteraction = "inspect" | "mutate" | "execute" | "delegate" | "ask" | "govern" | "generate";
 export type ToolBaseSchema = Readonly<Record<string, unknown>>;
-export type ToolBaseId = "shell.run" | "file.read" | "file.write" | "file.edit" | "file.search" | "patch.apply" | "web.search" | "web.fetch" | "plan.update" | "user.ask" | "agent.spawn" | "agent.message" | "agent.wait" | "skill.load" | "context.load" | "mcp.use" | "mcp.resources" | "lsp.query" | "browser.use" | "computer.use" | "image.view" | "image.generate" | "audio.transcribe" | "media.generate" | "memory.use" | "repo.inspect" | "approval.request" | "permission.check" | "sandbox.run" | "artifact.store" | "output.truncate" | "process.wait" | "process.kill" | "secret.resolve" | "tool.discover" | "tool.describe" | (string & {});
+export type ToolBaseId = "shell.run" | "file.read" | "file.write" | "file.edit" | "file.search" | "patch.apply" | "web.search" | "web.fetch" | "plan.update" | "user.ask" | "agent.spawn" | "agent.message" | "agent.wait" | "skill.load" | "context.load" | "mcp.use" | "mcp.resources" | "mcp.prompts" | "lsp.query" | "browser.use" | "computer.use" | "image.view" | "image.generate" | "audio.transcribe" | "media.generate" | "memory.use" | "repo.inspect" | "approval.request" | "permission.check" | "sandbox.run" | "artifact.store" | "output.truncate" | "process.wait" | "process.kill" | "secret.resolve" | "tool.discover" | "tool.describe" | (string & {});
 export type ToolBaseDefinition = {
     id: ToolBaseId;
     title: string;

package/examples/fullstack/agents/repoInspector/harness/repoInspectorHarness.ts

@@ -4,6 +4,26 @@ import type { HarnessSpec } from "@praxis-ai/praxis";
 import type { NormalizedRepoInspectorOptions } from "../config/repoInspectorOptions.js";
 import { createRepoInspectorToolSet } from "../tools/toolSet.js";
 
+const repoInspectorSkillModule = praxis.skill.module({
+  sources: [
+    praxis.skill.inline([{
+      skillId: "repo-review.findings-first",
+      title: "Findings First Review",
+      summary: "Lead with actionable findings and put summaries after risks.",
+      scope: "project",
+      whenToUse: "Code review and regression-risk tasks",
+      pitfallsPreview: ["Do not bury test gaps in a summary."],
+    }, {
+      skillId: "repo-inspection.anchor-current-target",
+      title: "Anchor Current Target",
+      summary: "Restate the current repository/path/task before inspecting or editing.",
+      scope: "project",
+      whenToUse: "Long context or task-switching sessions",
+      pitfallsPreview: ["Do not continue a previous repository by inertia."],
+    }]),
+  ],
+});
+
 export function createRepoInspectorHarness(options: NormalizedRepoInspectorOptions): HarnessSpec {
   return praxis.harness({
     modelRef: `model.repoInspector.${options.mode}`,
@@ -30,6 +50,9 @@ export function createRepoInspectorHarness(options: NormalizedRepoInspectorOptio
     memoryRefs: [
       "memory.example.fullstack.mpBridge.contract",
     ],
+    modules: {
+      skill: repoInspectorSkillModule,
+    },
     tools: praxis.tools(createRepoInspectorToolSet(options)),
     policy: praxis.policy({
       allowProviderCall: true,