@nestpilot/mcp-app 1.0.0

package/dist/src/skills/skill-executor.js

@@ -0,0 +1,174 @@
+import { checkCompatibility, } from "./skill-registry.js";
+import { evaluatePolicy, } from "../policy/policy-engine.js";
+/**
+ * Validates a payload against a skill I/O schema definition.
+ * Checks that all required fields are present and have the correct type.
+ */
+export function validateIO(payload, schema, direction) {
+    const errors = [];
+    for (const field of schema.fields) {
+        const value = payload[field.name];
+        if (field.required && (value === undefined || value === null)) {
+            errors.push(`${direction}.${field.name}: required field is missing`);
+            continue;
+        }
+        if (value !== undefined && value !== null) {
+            const actualType = Array.isArray(value) ? "array" : typeof value;
+            if (actualType !== field.type) {
+                errors.push(`${direction}.${field.name}: expected type '${field.type}', got '${actualType}'`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+    return { valid: true };
+}
+// ── Run ID generation ───────────────────────────────────────────────────
+let runCounter = 0;
+function generateRunId() {
+    runCounter += 1;
+    return `run-${Date.now()}-${runCounter}`;
+}
+// ── Executor ────────────────────────────────────────────────────────────
+/**
+ * Executes a skill by:
+ *   1. Running compatibility checks against tool contracts.
+ *   2. Validating input against the skill's input schema.
+ *   3. Evaluating policy for each required tool.
+ *   4. Calling each required tool via the injected dispatcher.
+ *   5. Validating output against the skill's output schema.
+ *   6. Returning an execution record with full trace.
+ */
+export async function executeSkill(manifest, ctx) {
+    const runId = generateRunId();
+    const startedAt = new Date().toISOString();
+    const stepTrace = [];
+    const policyDecisions = [];
+    // ── 1. Compatibility check ────────────────────────────────────────────
+    const compat = checkCompatibility(manifest);
+    if (!compat.compatible) {
+        return {
+            runId,
+            skillId: manifest.skillId,
+            version: manifest.version,
+            status: "blocked",
+            stepTrace,
+            policyDecisions,
+            startedAt,
+            completedAt: new Date().toISOString(),
+            error: `Compatibility check failed: ${compat.failures.map((f) => f.reason).join("; ")}`,
+        };
+    }
+    // ── 2. Validate input ─────────────────────────────────────────────────
+    const inputValidation = validateIO(ctx.input, manifest.inputSchema, "input");
+    if (!inputValidation.valid) {
+        return {
+            runId,
+            skillId: manifest.skillId,
+            version: manifest.version,
+            status: "error",
+            stepTrace,
+            policyDecisions,
+            startedAt,
+            completedAt: new Date().toISOString(),
+            error: `Input validation failed: ${inputValidation.errors.join("; ")}`,
+        };
+    }
+    // ── 3. Execute each required tool step ────────────────────────────────
+    let accumulatedOutput = { ...ctx.input };
+    for (const req of manifest.requiredTools) {
+        const stepStart = Date.now();
+        // Policy evaluation
+        const decision = evaluatePolicy({
+            actorId: ctx.actorId,
+            role: ctx.role,
+            toolName: req.toolName,
+        });
+        policyDecisions.push(decision);
+        if (decision.decision === "deny") {
+            stepTrace.push({
+                toolName: req.toolName,
+                status: "blocked",
+                durationMs: Date.now() - stepStart,
+                policyDecision: decision,
+            });
+            return {
+                runId,
+                skillId: manifest.skillId,
+                version: manifest.version,
+                status: "blocked",
+                stepTrace,
+                policyDecisions,
+                startedAt,
+                completedAt: new Date().toISOString(),
+                error: `Policy blocked tool '${req.toolName}': ${decision.reasonCodes.join(", ")}`,
+            };
+        }
+        // Tool invocation
+        try {
+            const result = await ctx.callTool(req.toolName, accumulatedOutput);
+            if (result && typeof result === "object") {
+                accumulatedOutput = { ...accumulatedOutput, ...result };
+            }
+            stepTrace.push({
+                toolName: req.toolName,
+                status: "executed",
+                durationMs: Date.now() - stepStart,
+                policyDecision: decision,
+            });
+        }
+        catch (err) {
+            stepTrace.push({
+                toolName: req.toolName,
+                status: "skipped",
+                durationMs: Date.now() - stepStart,
+                policyDecision: decision,
+            });
+            return {
+                runId,
+                skillId: manifest.skillId,
+                version: manifest.version,
+                status: "error",
+                stepTrace,
+                policyDecisions,
+                startedAt,
+                completedAt: new Date().toISOString(),
+                error: `Tool '${req.toolName}' execution failed: ${String(err)}`,
+            };
+        }
+    }
+    // ── 4. Validate output ────────────────────────────────────────────────
+    const outputValidation = validateIO(accumulatedOutput, manifest.outputSchema, "output");
+    if (!outputValidation.valid) {
+        return {
+            runId,
+            skillId: manifest.skillId,
+            version: manifest.version,
+            status: "error",
+            stepTrace,
+            policyDecisions,
+            startedAt,
+            completedAt: new Date().toISOString(),
+            output: accumulatedOutput,
+            error: `Output validation failed: ${outputValidation.errors.join("; ")}`,
+        };
+    }
+    return {
+        runId,
+        skillId: manifest.skillId,
+        version: manifest.version,
+        status: "success",
+        stepTrace,
+        policyDecisions,
+        startedAt,
+        completedAt: new Date().toISOString(),
+        output: accumulatedOutput,
+    };
+}
+/**
+ * Resets the run counter (for testing only).
+ */
+export function _resetRunCounter() {
+    runCounter = 0;
+}

package/dist/src/skills/skill-manifest-schema.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Skill Manifest v1 Schema — FEAT-0057
+ *
+ * Defines the versioned manifest format for NestPilot retirement skills.
+ * Each skill declares input/output contracts, safety constraints,
+ * required tool dependencies, and minimum contract versions.
+ *
+ * @feature FEAT-0057
+ * @design DES-0055
+ */
+import { z } from "zod";
+export declare const SkillConstraintSchema: z.ZodObject<{
+    /** Human-readable constraint description. */
+    description: z.ZodString;
+    /** Whether this constraint is enforced at runtime (vs. advisory). */
+    enforced: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    enforced: boolean;
+}, {
+    description: string;
+    enforced: boolean;
+}>;
+export declare const RequiredToolSchema: z.ZodObject<{
+    /** Tool name as registered in the contract registry. */
+    toolName: z.ZodString;
+    /** Minimum contract version required (semver). */
+    minContractVersion: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    toolName: string;
+    minContractVersion: string;
+}, {
+    toolName: string;
+    minContractVersion: string;
+}>;
+export declare const SkillIOFieldSchema: z.ZodObject<{
+    /** Field name. */
+    name: z.ZodString;
+    /** JSON Schema type (string, number, object, array, boolean). */
+    type: z.ZodEnum<["string", "number", "object", "array", "boolean"]>;
+    /** Whether this field is required. */
+    required: z.ZodBoolean;
+    /** Human-readable description. */
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "string" | "number" | "boolean" | "object" | "array";
+    description: string;
+    required: boolean;
+}, {
+    name: string;
+    type: "string" | "number" | "boolean" | "object" | "array";
+    description: string;
+    required: boolean;
+}>;
+export declare const SkillIOSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodObject<{
+        /** Field name. */
+        name: z.ZodString;
+        /** JSON Schema type (string, number, object, array, boolean). */
+        type: z.ZodEnum<["string", "number", "object", "array", "boolean"]>;
+        /** Whether this field is required. */
+        required: z.ZodBoolean;
+        /** Human-readable description. */
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        type: "string" | "number" | "boolean" | "object" | "array";
+        description: string;
+        required: boolean;
+    }, {
+        name: string;
+        type: "string" | "number" | "boolean" | "object" | "array";
+        description: string;
+        required: boolean;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    fields: {
+        name: string;
+        type: "string" | "number" | "boolean" | "object" | "array";
+        description: string;
+        required: boolean;
+    }[];
+}, {
+    fields: {
+        name: string;
+        type: "string" | "number" | "boolean" | "object" | "array";
+        description: string;
+        required: boolean;
+    }[];
+}>;
+export declare const SkillExampleSchema: z.ZodObject<{
+    /** Short description of the example scenario. */
+    description: z.ZodString;
+    /** Example input payload. */
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    /** Expected output structure (may be partial). */
+    expectedOutput: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    input: Record<string, unknown>;
+    description: string;
+    expectedOutput: Record<string, unknown>;
+}, {
+    input: Record<string, unknown>;
+    description: string;
+    expectedOutput: Record<string, unknown>;
+}>;
+export declare const SkillManifestV1Schema: z.ZodObject<{
+    /** Unique skill identifier (kebab-case). */
+    skillId: z.ZodString;
+    /** Semver version string. */
+    version: z.ZodString;
+    /** Human-readable display name. */
+    displayName: z.ZodString;
+    /** Skill description (max 300 chars for Tier 0 token budget). */
+    description: z.ZodString;
+    /** Skill pack this manifest belongs to. */
+    pack: z.ZodString;
+    /** Tools this skill requires with minimum contract versions. */
+    requiredTools: z.ZodArray<z.ZodObject<{
+        /** Tool name as registered in the contract registry. */
+        toolName: z.ZodString;
+        /** Minimum contract version required (semver). */
+        minContractVersion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        toolName: string;
+        minContractVersion: string;
+    }, {
+        toolName: string;
+        minContractVersion: string;
+    }>, "many">;
+    /** Typed input schema. */
+    inputSchema: z.ZodObject<{
+        fields: z.ZodArray<z.ZodObject<{
+            /** Field name. */
+            name: z.ZodString;
+            /** JSON Schema type (string, number, object, array, boolean). */
+            type: z.ZodEnum<["string", "number", "object", "array", "boolean"]>;
+            /** Whether this field is required. */
+            required: z.ZodBoolean;
+            /** Human-readable description. */
+            description: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }, {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        fields: {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }[];
+    }, {
+        fields: {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }[];
+    }>;
+    /** Typed output schema. */
+    outputSchema: z.ZodObject<{
+        fields: z.ZodArray<z.ZodObject<{
+            /** Field name. */
+            name: z.ZodString;
+            /** JSON Schema type (string, number, object, array, boolean). */
+            type: z.ZodEnum<["string", "number", "object", "array", "boolean"]>;
+            /** Whether this field is required. */
+            required: z.ZodBoolean;
+            /** Human-readable description. */
+            description: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }, {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        fields: {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }[];
+    }, {
+        fields: {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }[];
+    }>;
+    /** Safety and behavioral constraints. */
+    constraints: z.ZodArray<z.ZodObject<{
+        /** Human-readable constraint description. */
+        description: z.ZodString;
+        /** Whether this constraint is enforced at runtime (vs. advisory). */
+        enforced: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        enforced: boolean;
+    }, {
+        description: string;
+        enforced: boolean;
+    }>, "many">;
+    /** Non-permitted actions — things this skill must never do. */
+    nonPermittedActions: z.ZodArray<z.ZodString, "many">;
+    /** Sensitive data declarations. */
+    sensitiveDataRequirements: z.ZodArray<z.ZodString, "many">;
+    /** Example input/output pairs. */
+    examples: z.ZodArray<z.ZodObject<{
+        /** Short description of the example scenario. */
+        description: z.ZodString;
+        /** Example input payload. */
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        /** Expected output structure (may be partial). */
+        expectedOutput: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        input: Record<string, unknown>;
+        description: string;
+        expectedOutput: Record<string, unknown>;
+    }, {
+        input: Record<string, unknown>;
+        description: string;
+        expectedOutput: Record<string, unknown>;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    description: string;
+    skillId: string;
+    displayName: string;
+    pack: string;
+    requiredTools: {
+        toolName: string;
+        minContractVersion: string;
+    }[];
+    inputSchema: {
+        fields: {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }[];
+    };
+    outputSchema: {
+        fields: {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }[];
+    };
+    constraints: {
+        description: string;
+        enforced: boolean;
+    }[];
+    nonPermittedActions: string[];
+    sensitiveDataRequirements: string[];
+    examples: {
+        input: Record<string, unknown>;
+        description: string;
+        expectedOutput: Record<string, unknown>;
+    }[];
+}, {
+    version: string;
+    description: string;
+    skillId: string;
+    displayName: string;
+    pack: string;
+    requiredTools: {
+        toolName: string;
+        minContractVersion: string;
+    }[];
+    inputSchema: {
+        fields: {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }[];
+    };
+    outputSchema: {
+        fields: {
+            name: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description: string;
+            required: boolean;
+        }[];
+    };
+    constraints: {
+        description: string;
+        enforced: boolean;
+    }[];
+    nonPermittedActions: string[];
+    sensitiveDataRequirements: string[];
+    examples: {
+        input: Record<string, unknown>;
+        description: string;
+        expectedOutput: Record<string, unknown>;
+    }[];
+}>;
+export type SkillConstraint = z.infer<typeof SkillConstraintSchema>;
+export type RequiredTool = z.infer<typeof RequiredToolSchema>;
+export type SkillIOField = z.infer<typeof SkillIOFieldSchema>;
+export type SkillIO = z.infer<typeof SkillIOSchema>;
+export type SkillExample = z.infer<typeof SkillExampleSchema>;
+export type SkillManifestV1 = z.infer<typeof SkillManifestV1Schema>;
+export interface ManifestValidationResult {
+    valid: true;
+    manifest: SkillManifestV1;
+}
+export interface ManifestValidationError {
+    valid: false;
+    errors: string[];
+}
+export type ManifestValidation = ManifestValidationResult | ManifestValidationError;
+/**
+ * Validates a raw object against the Skill Manifest v1 schema.
+ */
+export declare function validateManifest(raw: unknown): ManifestValidation;
+/**
+ * Validates and returns the manifest or throws.
+ */
+export declare function requireValidManifest(raw: unknown): SkillManifestV1;

package/dist/src/skills/skill-manifest-schema.js

@@ -0,0 +1,94 @@
+/**
+ * Skill Manifest v1 Schema — FEAT-0057
+ *
+ * Defines the versioned manifest format for NestPilot retirement skills.
+ * Each skill declares input/output contracts, safety constraints,
+ * required tool dependencies, and minimum contract versions.
+ *
+ * @feature FEAT-0057
+ * @design DES-0055
+ */
+import { z } from "zod";
+// ── Zod Schemas ─────────────────────────────────────────────────────────
+export const SkillConstraintSchema = z.object({
+    /** Human-readable constraint description. */
+    description: z.string().min(1),
+    /** Whether this constraint is enforced at runtime (vs. advisory). */
+    enforced: z.boolean(),
+});
+export const RequiredToolSchema = z.object({
+    /** Tool name as registered in the contract registry. */
+    toolName: z.string().min(1),
+    /** Minimum contract version required (semver). */
+    minContractVersion: z.string().regex(/^\d+\.\d+\.\d+$/, "Must be semver"),
+});
+export const SkillIOFieldSchema = z.object({
+    /** Field name. */
+    name: z.string().min(1),
+    /** JSON Schema type (string, number, object, array, boolean). */
+    type: z.enum(["string", "number", "object", "array", "boolean"]),
+    /** Whether this field is required. */
+    required: z.boolean(),
+    /** Human-readable description. */
+    description: z.string().min(1),
+});
+export const SkillIOSchema = z.object({
+    fields: z.array(SkillIOFieldSchema).min(1),
+});
+export const SkillExampleSchema = z.object({
+    /** Short description of the example scenario. */
+    description: z.string().min(1),
+    /** Example input payload. */
+    input: z.record(z.unknown()),
+    /** Expected output structure (may be partial). */
+    expectedOutput: z.record(z.unknown()),
+});
+export const SkillManifestV1Schema = z.object({
+    /** Unique skill identifier (kebab-case). */
+    skillId: z.string().regex(/^[a-z][a-z0-9-]*$/, "Must be kebab-case"),
+    /** Semver version string. */
+    version: z.string().regex(/^\d+\.\d+\.\d+$/, "Must be semver"),
+    /** Human-readable display name. */
+    displayName: z.string().min(1),
+    /** Skill description (max 300 chars for Tier 0 token budget). */
+    description: z.string().min(1).max(300),
+    /** Skill pack this manifest belongs to. */
+    pack: z.string().min(1),
+    /** Tools this skill requires with minimum contract versions. */
+    requiredTools: z.array(RequiredToolSchema).min(1),
+    /** Typed input schema. */
+    inputSchema: SkillIOSchema,
+    /** Typed output schema. */
+    outputSchema: SkillIOSchema,
+    /** Safety and behavioral constraints. */
+    constraints: z.array(SkillConstraintSchema).min(1),
+    /** Non-permitted actions — things this skill must never do. */
+    nonPermittedActions: z.array(z.string().min(1)),
+    /** Sensitive data declarations. */
+    sensitiveDataRequirements: z.array(z.string()),
+    /** Example input/output pairs. */
+    examples: z.array(SkillExampleSchema).min(1),
+});
+/**
+ * Validates a raw object against the Skill Manifest v1 schema.
+ */
+export function validateManifest(raw) {
+    const result = SkillManifestV1Schema.safeParse(raw);
+    if (result.success) {
+        return { valid: true, manifest: result.data };
+    }
+    return {
+        valid: false,
+        errors: result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`),
+    };
+}
+/**
+ * Validates and returns the manifest or throws.
+ */
+export function requireValidManifest(raw) {
+    const result = validateManifest(raw);
+    if (!result.valid) {
+        throw new Error(`Skill manifest validation failed:\n  ${result.errors.join("\n  ")}`);
+    }
+    return result.manifest;
+}

package/dist/src/skills/skill-registry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Skill Registry — FEAT-0057
+ *
+ * Loads, validates, and indexes v1 skill manifests.
+ * Performs compatibility checks against FEAT-0056 tool contracts
+ * to ensure required tool versions are available before execution.
+ *
+ * @feature FEAT-0057
+ * @design DES-0055
+ */
+import { type SkillManifestV1, type ManifestValidation } from "./skill-manifest-schema.js";
+export interface CompatibilityCheckResult {
+    compatible: true;
+    skillId: string;
+    checkedTools: string[];
+}
+export interface CompatibilityToolFailure {
+    toolName: string;
+    requiredVersion: string;
+    reason: string;
+}
+export interface CompatibilityCheckFailure {
+    compatible: false;
+    skillId: string;
+    failures: CompatibilityToolFailure[];
+}
+export type CompatibilityCheck = CompatibilityCheckResult | CompatibilityCheckFailure;
+export interface SkillLookupResult {
+    found: true;
+    manifest: SkillManifestV1;
+}
+export interface SkillLookupMiss {
+    found: false;
+    skillId: string;
+    reason: string;
+}
+export type SkillLookup = SkillLookupResult | SkillLookupMiss;
+/**
+ * Returns true if `actual` >= `required` (semver).
+ */
+export declare function semverSatisfies(actual: string, required: string): boolean;
+/**
+ * Registers a validated skill manifest in the registry.
+ * Returns validation result; rejects invalid manifests.
+ */
+export declare function registerSkill(raw: unknown): ManifestValidation;
+/**
+ * Look up a registered skill by ID.
+ */
+export declare function lookupSkill(skillId: string): SkillLookup;
+/**
+ * Returns all registered skill manifests.
+ */
+export declare function getAllSkills(): ReadonlyArray<SkillManifestV1>;
+/**
+ * Checks whether all required tools for a skill are available
+ * in the contract registry with sufficient versions.
+ *
+ * This is the compatibility gate: execution MUST be blocked
+ * if any required tool contract is missing or below the
+ * minimum version.
+ */
+export declare function checkCompatibility(manifest: SkillManifestV1): CompatibilityCheck;
+/**
+ * Checks compatibility and throws if requirements are not met.
+ */
+export declare function requireCompatibility(manifest: SkillManifestV1): CompatibilityCheckResult;
+/**
+ * Clears all registered skills (for testing only).
+ */
+export declare function _resetSkillRegistry(): void;