@hasna/skills 0.1.56 → 0.1.58

package/bin/index.js

@@ -36860,7 +36860,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.1.56",
+    version: "0.1.58",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -57778,6 +57778,65 @@ var init_auth_store = __esm(() => {
   LEGACY_AUTH_FILE = join9(homedir4(), ".skills", "auth.json");
 });
 
+// src/lib/hosted-availability.ts
+var exports_hosted_availability = {};
+__export(exports_hosted_availability, {
+  getHostedRunAvailability: () => getHostedRunAvailability,
+  getHostedAvailabilityMetadata: () => getHostedAvailabilityMetadata
+});
+function getHostedRunAvailability(slug) {
+  const canonicalSlug = resolveSkillAlias(slug);
+  if (!UNAVAILABLE_HOSTED_PROVIDER_SKILLS.has(canonicalSlug)) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    status: 503,
+    code: "HOSTED_PROVIDER_UNAVAILABLE",
+    message: "hosted execution is temporarily unavailable for this skill",
+    details: [
+      "This skill requires a platform-managed execution path that is not enabled for live hosted runs yet.",
+      "No balance was charged."
+    ]
+  };
+}
+function getHostedAvailabilityMetadata(slug) {
+  const availability = getHostedRunAvailability(slug);
+  if (availability.ok)
+    return { status: "available" };
+  return {
+    status: "unavailable",
+    code: availability.code,
+    message: availability.message,
+    details: availability.details
+  };
+}
+var UNAVAILABLE_HOSTED_PROVIDER_SKILLS;
+var init_hosted_availability = __esm(() => {
+  init_skill_aliases();
+  UNAVAILABLE_HOSTED_PROVIDER_SKILLS = new Set([
+    "audio",
+    "brand-photo-shoot",
+    "browse",
+    "deepresearch",
+    "generate-book-cover",
+    "icon-pack",
+    "image",
+    "music",
+    "music-album",
+    "pdf-read",
+    "photo-album",
+    "playlist-maker",
+    "read-pdf",
+    "remove-background",
+    "short-video-pack",
+    "transcript",
+    "video",
+    "voiceover-jingle-pack",
+    "webcrawling"
+  ]);
+});
+
 // src/lib/remote-registry.ts
 function getConfiguredApiUrl(config2 = loadConfig(), env3 = process.env) {
   const raw = env3["SKILLS_API_URL"] || config2.apiUrl;
@@ -57819,9 +57878,30 @@ function normalizeRemoteSkill(skill) {
     dependencies: skill.dependencies,
     ...skill.version ? { version: skill.version } : {},
     ...skill.pricing ? { pricing: skill.pricing } : {},
+    availability: normalizeRemoteAvailability(name, skill.availability),
     source: "remote"
   };
 }
+function normalizeRemoteAvailability(name, availability) {
+  if (!availability)
+    return getHostedAvailabilityMetadata(name);
+  if (availability.status === "available")
+    return { status: "available" };
+  return {
+    status: availability.status,
+    ...safeAvailabilityCode(availability.code) ? { code: safeAvailabilityCode(availability.code) } : {},
+    ...availability.message ? { message: sanitizeAvailabilityText(availability.message) } : {},
+    ...availability.details ? { details: availability.details.map(sanitizeAvailabilityText).filter(Boolean) } : {}
+  };
+}
+function safeAvailabilityCode(code) {
+  if (!code)
+    return;
+  return /^[A-Z0-9_]+$/.test(code) ? code : undefined;
+}
+function sanitizeAvailabilityText(text) {
+  return secretValuePatterns.reduce((value, pattern) => value.replace(pattern, "credential"), sanitizePublicDiscoveryText(text).replace(/\b[A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|CREDENTIAL)[A-Z0-9_]*\b/g, "credential")).replace(/\s{2,}/g, " ").trim();
+}
 function parseRemoteRegistryPayload(payload) {
   const parsed = parseRemoteContract(remoteRegistrySchema, payload, "Remote registry payload did not match the expected skills contract");
   const rawSkills = Array.isArray(parsed) ? parsed : ("skills" in parsed) ? parsed.skills : parsed.data;
@@ -57883,11 +57963,19 @@ async function loadRemoteSkill(name, options = {}) {
   const url2 = buildSkillsApiUrl(apiUrl, options.endpoint ?? `/skills/${slug}`);
   return parseRemoteSkillPayload(await fetchRemoteJson(url2, options));
 }
-var remotePricingSchema, remoteSkillSchema, remoteSkillDetailSchema, remoteRegistrySchema;
+var remoteAvailabilitySchema, remotePricingSchema, remoteSkillSchema, secretValuePatterns, remoteSkillDetailSchema, remoteRegistrySchema;
 var init_remote_registry = __esm(() => {
   init_zod();
   init_auth_store();
   init_config();
+  init_discovery();
+  init_hosted_availability();
+  remoteAvailabilitySchema = exports_external.object({
+    status: exports_external.enum(["available", "unavailable"]),
+    code: exports_external.string().optional(),
+    message: exports_external.string().optional(),
+    details: exports_external.array(exports_external.string()).optional()
+  }).passthrough();
   remotePricingSchema = exports_external.object({
     formattedCost: exports_external.string(),
     tier: exports_external.string().optional(),
@@ -57909,10 +57997,22 @@ var init_remote_registry = __esm(() => {
     tags: exports_external.array(exports_external.string()).optional(),
     dependencies: exports_external.array(exports_external.string()).optional(),
     version: exports_external.string().optional(),
-    pricing: remotePricingSchema.optional()
+    pricing: remotePricingSchema.optional(),
+    availability: remoteAvailabilitySchema.optional()
   }).passthrough().refine((skill) => skill.name || skill.slug, {
     message: "Remote skill requires name or slug"
   });
+  secretValuePatterns = [
+    /\bsk-[A-Za-z0-9_-]{8,}\b/g,
+    /\bgh[opsur]_[A-Za-z0-9_]{8,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{8,}\b/g,
+    /\bnpm_[A-Za-z0-9_]{8,}\b/g,
+    /\bAKIA[A-Z0-9]{12,}\b/g,
+    /\bAIza[A-Za-z0-9_-]{10,}\b/g,
+    new RegExp("\\bsecret" + "-token:\\s*[A-Za-z0-9._-]+", "gi"),
+    /\bctx7sk\-[A-Za-z0-9_-]{8,}\b/g,
+    /\bxai\-[A-Za-z0-9_-]{8,}\b/g
+  ];
   remoteSkillDetailSchema = exports_external.union([
     remoteSkillSchema,
     exports_external.object({ skill: remoteSkillSchema }),
@@ -75774,7 +75874,7 @@ var MCP_CONTRACT_SCHEMA_VERSION = 1, stringSchema = (description) => ({
   type: "array",
   items,
   ...description ? { description } : {}
-}), skillNameInput, optionalAgentInput, scopeInput, runInputSchema, runArgsSchema, paidRunApprovalSchema, errorSchema, pricingSchema, skillSummarySchema, toolPrimitiveSummarySchema, skillToolDependencySchema, validationMessageSchema, validationOutputSchema, installOutputSchema, runOutputSchema, toolContracts, contracts, resourceContracts;
+}), skillNameInput, optionalAgentInput, scopeInput, runInputSchema, runArgsSchema, paidRunApprovalSchema, errorSchema, pricingSchema, skillAvailabilitySchema, skillSummarySchema, toolPrimitiveSummarySchema, skillToolDependencySchema, validationMessageSchema, validationOutputSchema, installOutputSchema, runOutputSchema, toolContracts, contracts, resourceContracts;
 var init_mcp_contracts = __esm(() => {
   skillNameInput = stringSchema("skill name or alias.");
   optionalAgentInput = stringSchema("Optional target agent slug. Use MCP registration instead of direct skill-folder installs.");
@@ -75812,6 +75912,16 @@ var init_mcp_contracts = __esm(() => {
     quoteDependsOnInput: { type: "boolean", description: "Whether input affects the quote." },
     quoteRequired: { type: "boolean", description: "Whether callers should quote before running." }
   }, [], "Public pricing metadata.");
+  skillAvailabilitySchema = objectSchema({
+    status: {
+      type: "string",
+      enum: ["available", "unavailable"],
+      description: "Whether hosted execution is currently available for this skill."
+    },
+    code: stringSchema("Optional stable unavailability code."),
+    message: stringSchema("Optional human-readable availability message."),
+    details: stringArraySchema("Optional availability details.")
+  }, ["status"], "Hosted skill availability metadata.");
   skillSummarySchema = objectSchema({
     name: stringSchema("Canonical skill slug."),
     category: stringSchema("Skill category."),
@@ -76167,7 +76277,14 @@ var init_mcp_contracts = __esm(() => {
       sideEffects: "none",
       stable: true,
       inputSchema: objectSchema({ name: skillNameInput, input: runInputSchema, args: runArgsSchema }, ["name"]),
-      outputSchema: objectSchema({ skill: stringSchema("Skill slug."), pricing: pricingSchema }, ["skill", "pricing"])
+      outputSchema: objectSchema({
+        skill: stringSchema("Skill slug."),
+        pricing: pricingSchema,
+        availability: skillAvailabilitySchema,
+        error: stringSchema("Optional error message when the quote cannot be used to run."),
+        code: stringSchema("Optional stable error code."),
+        details: stringArraySchema("Optional error details.")
+      }, ["skill", "pricing", "availability"])
     },
     {
       name: "run_skill",
@@ -77014,9 +77131,33 @@ function registerOperationTools(server) {
         return mcpError("INVALID_BLOG_ARTICLE_OPTIONS", validation.errors.join(" "));
       }
     }
+    const pricing = getPublicSkillPricing2(skill.name, runInput, runArgs);
+    const hostedAvailability = getHostedRunAvailability(skill.name);
+    if (!hostedAvailability.ok) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            skill: skill.name,
+            pricing,
+            error: hostedAvailability.message,
+            code: hostedAvailability.code,
+            details: hostedAvailability.details,
+            availability: {
+              status: "unavailable",
+              code: hostedAvailability.code,
+              message: hostedAvailability.message,
+              details: hostedAvailability.details
+            }
+          })
+        }],
+        isError: true
+      };
+    }
     return mcpJson({
       skill: skill.name,
-      pricing: getPublicSkillPricing2(skill.name, runInput, runArgs)
+      pricing,
+      availability: { status: "available" }
     });
   });
   server.registerTool("run_skill", {
@@ -77059,6 +77200,18 @@ function registerOperationTools(server) {
       remote: isPremiumSkill2(skillName),
       costCents
     });
+    if (isPremiumSkill2(skillName)) {
+      const hostedAvailability = getHostedRunAvailability(skillName);
+      if (!hostedAvailability.ok) {
+        const error48 = `${hostedAvailability.code}: ${hostedAvailability.message}`;
+        writeRunLogs(runContext, "", `${error48}
+${hostedAvailability.details.join(`
+`)}
+`);
+        const run = completeSkillRun(runContext, { status: "failed", error: error48, costCents });
+        return mcpError(hostedAvailability.code, `${hostedAvailability.message}. ${hostedAvailability.details.join(" ")} Local run metadata: ${run.paths.runDir}/run.json`);
+      }
+    }
     if (isPremiumSkill2(skillName) && !apiKey) {
       const cost = formatCost2(costCents ?? 0);
       const error48 = `${skillName} is a hosted skill (${cost}). Run: skills setup --mode hosted && skills auth login`;
@@ -77302,6 +77455,7 @@ var init_operation_tools = __esm(() => {
   init_run_state();
   init_portable_skills();
   init_helpers();
+  init_hosted_availability();
 });
 
 // src/lib/feedback.ts
@@ -78710,7 +78864,20 @@ function handleQuote(name, args2, options) {
     }
   }
   const pricing = getPublicSkillPricing(skill.name, {}, quoteArgs);
-  const payload = { skill: skill.name, pricing };
+  const hostedAvailability = getHostedRunAvailability(skill.name);
+  if (!hostedAvailability.ok) {
+    const payload2 = unavailableHostedPayload(skill.name, pricing, hostedAvailability);
+    if (json2) {
+      console.log(JSON.stringify(payload2, null, 2));
+    } else {
+      console.error(source_default.red(`${skill.name}: ${hostedAvailability.message}`));
+      for (const detail of hostedAvailability.details)
+        console.error(source_default.dim(`  ${detail}`));
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const payload = { skill: skill.name, pricing, availability: { status: "available" } };
   if (json2) {
     console.log(JSON.stringify(payload, null, 2));
     return;
@@ -78760,6 +78927,32 @@ async function handleRun(name, args2, options) {
     costCents
   });
   if (isPremium) {
+    const hostedAvailability = getHostedRunAvailability(skill.name);
+    if (!hostedAvailability.ok) {
+      const payload = unavailableHostedPayload(skill.name, publicPricing, hostedAvailability);
+      const error48 = `${hostedAvailability.code}: ${hostedAvailability.message}`;
+      writeRunLogs(runContext, "", `${error48}
+${hostedAvailability.details.join(`
+`)}
+`);
+      const run = completeSkillRun(runContext, { status: "failed", error: error48, costCents });
+      if (options.json) {
+        console.log(JSON.stringify({
+          contractVersion: REMOTE_SKILL_RUN_CONTRACT_VERSION,
+          args: args2,
+          exitCode: 1,
+          remote: true,
+          ...payload,
+          run
+        }, null, 2));
+      } else {
+        console.error(source_default.red(`${skill.name}: ${hostedAvailability.message}`));
+        for (const detail of hostedAvailability.details)
+          console.error(source_default.dim(`  ${detail}`));
+      }
+      process.exitCode = 1;
+      return;
+    }
     const { getApiKey: getApiKey2 } = await Promise.resolve().then(() => (init_auth_store(), exports_auth_store));
     const apiKey = getApiKey2();
     if (!apiKey) {
@@ -78912,6 +79105,21 @@ async function handleRun(name, args2, options) {
   }
   process.exitCode = result2.exitCode;
 }
+function unavailableHostedPayload(skill, pricing, availability) {
+  return {
+    skill,
+    pricing,
+    error: availability.message,
+    code: availability.code,
+    details: availability.details,
+    availability: {
+      status: "unavailable",
+      code: availability.code,
+      message: availability.message,
+      details: availability.details
+    }
+  };
+}
 async function approvePaidHostedRun(params) {
   if (params.yes)
     return { approved: true };
@@ -79355,6 +79563,7 @@ var init_runtime = __esm(() => {
   init_skillinfo();
   init_pricing();
   init_config();
+  init_hosted_availability();
   init_run_state();
   init_runtime_mcp();
 });
@@ -79822,6 +80031,18 @@ Next: skills schedule list --cursor ${page.nextOffset} --limit ${page.limit}`));
       return;
     }
     const dueDetails = await Promise.all(due.map((schedule) => describeDueSchedule(schedule)));
+    const unavailable = dueDetails.filter((schedule) => schedule.availability?.status === "unavailable");
+    if (unavailable.length > 0 && !options.dryRun) {
+      const code = unavailable[0]?.availability?.code ?? "HOSTED_PROVIDER_UNAVAILABLE";
+      const error48 = `Hosted execution is temporarily unavailable for ${unavailable.map((schedule) => schedule.skill).join(", ")}. No balance was charged.`;
+      if (options.json) {
+        console.log(JSON.stringify({ ran: 0, error: error48, code, unavailable, schedules: dueDetails }));
+      } else {
+        console.error(source_default.red(`\u2717 ${error48}`));
+      }
+      process.exitCode = 1;
+      return;
+    }
     const paidTotalCents = dueDetails.reduce((total, schedule) => total + (schedule.costCents ?? 0), 0);
     if (options.dryRun) {
       console.log(options.json ? JSON.stringify({ due: dueDetails, paidTotalCents, paidTotal: formatCost2(paidTotalCents) }) : source_default.bold(`${due.length} schedule(s) due:
@@ -79907,6 +80128,11 @@ async function executeScheduledSkill(skillName, args2, options) {
     throw new Error(`Skill '${skillName}' not found`);
   const pricing = await Promise.resolve().then(() => (init_pricing(), exports_pricing));
   if (pricing.isPremiumSkill(skill.name)) {
+    const { getHostedRunAvailability: getHostedRunAvailability2 } = await Promise.resolve().then(() => (init_hosted_availability(), exports_hosted_availability));
+    const hostedAvailability = getHostedRunAvailability2(skill.name);
+    if (!hostedAvailability.ok) {
+      throw new Error(`${hostedAvailability.code}: ${hostedAvailability.message}. ${hostedAvailability.details.join(" ")}`);
+    }
     const publicPricing = pricing.getPublicSkillPricing(skill.name, {}, args2);
     if (!options.allowPaid) {
       throw new Error(`${skill.name} is a paid hosted skill (${publicPricing.formattedCost}). Review with skills schedule run --dry-run, then rerun with --allow-paid --max-paid-cents ${publicPricing.costCents}.`);
@@ -79933,16 +80159,24 @@ async function executeScheduledSkill(skillName, args2, options) {
 async function describeDueSchedule(schedule) {
   const { getSkill: getSkill2 } = await Promise.resolve().then(() => (init_registry(), exports_registry));
   const pricing = await Promise.resolve().then(() => (init_pricing(), exports_pricing));
+  const { getHostedRunAvailability: getHostedRunAvailability2 } = await Promise.resolve().then(() => (init_hosted_availability(), exports_hosted_availability));
   const skill = getSkill2(schedule.skill);
   const paid = Boolean(skill && pricing.isPremiumSkill(skill.name));
   const publicPricing = paid && skill ? pricing.getPublicSkillPricing(skill.name, {}, schedule.args ?? []) : null;
+  const availability = skill ? getHostedRunAvailability2(skill.name) : { ok: true };
   return {
     name: schedule.name,
     skill: schedule.skill,
     cron: schedule.cron,
     paid,
     costCents: publicPricing?.costCents,
-    cost: publicPricing?.formattedCost
+    cost: publicPricing?.formattedCost,
+    availability: availability.ok ? { status: "available" } : {
+      status: "unavailable",
+      code: availability.code,
+      message: availability.message,
+      details: availability.details
+    }
   };
 }
 function parseMaxPaidCents(value) {
@@ -80164,6 +80398,54 @@ function writeCommandError(err, fallback, json2) {
     console.error(source_default.red(String(payload.detail || payload.error || fallback)));
   process.exitCode = 1;
 }
+function envApiKey() {
+  const key = process.env.SKILLS_API_KEY || process.env.SKILL_API_KEY;
+  const trimmed = key?.trim();
+  return trimmed || null;
+}
+function stringField2(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function recordField(value) {
+  return isRecord3(value) ? value : undefined;
+}
+function authIdentityPayload(authSource, live, cached2, offline = false) {
+  const root = recordField(live) ?? {};
+  const data = recordField(root.data);
+  const user = recordField(root.user) ?? recordField(data?.user);
+  const organization = recordField(root.organization) ?? recordField(root.org) ?? recordField(data?.organization);
+  const email3 = stringField2(user?.email) ?? cached2?.email;
+  const orgSlug = stringField2(organization?.slug) ?? cached2?.orgSlug;
+  const orgName = stringField2(organization?.name);
+  const userId = stringField2(user?.id) ?? cached2?.userId;
+  const orgId = stringField2(organization?.id) ?? cached2?.orgId;
+  const role = stringField2(user?.role);
+  return {
+    status: "authenticated",
+    authSource,
+    ...offline ? { offline: true } : {},
+    ...email3 ? { email: email3 } : {},
+    ...orgSlug ? { organization: orgSlug } : {},
+    ...orgName ? { organizationName: orgName } : {},
+    ...userId ? { userId } : {},
+    ...orgId ? { orgId } : {},
+    ...role ? { role } : {}
+  };
+}
+function printWhoami(payload) {
+  if (payload.email)
+    console.log(source_default.bold("Email:  ") + payload.email);
+  if (payload.organization)
+    console.log(source_default.bold("Org:    ") + payload.organization);
+  if (payload.role)
+    console.log(source_default.bold("Role:   ") + payload.role);
+  if (payload.organizationName)
+    console.log(source_default.bold("Name:   ") + payload.organizationName);
+  if (payload.authSource === "env")
+    console.log(source_default.dim("Auth:   SKILLS_API_KEY"));
+  if (payload.offline)
+    console.log(source_default.dim("(offline \u2014 showing cached info)"));
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -80428,26 +80710,39 @@ function registerAuth(parent) {
     clearAuthConfig();
     console.log(source_default.green(`\u2713 Signed out (was ${existing.email})`));
   });
-  auth.command("whoami").description("Show current account info").action(async () => {
+  auth.command("whoami").description("Show current account info").option("--json", "Output as JSON", false).action(async (options) => {
+    const envKey = envApiKey();
     const config2 = getAuthConfig();
-    if (!config2) {
-      console.log(source_default.dim("Not signed in. Run: skills auth login"));
+    const apiKey = envKey ?? config2?.apiKey;
+    if (!apiKey) {
+      const payload = { status: "unauthenticated", error: "Not signed in. Run: skills auth login" };
+      if (options.json)
+        console.log(JSON.stringify(payload, null, 2));
+      else
+        console.log(source_default.dim(payload.error));
       return;
     }
-    console.log(source_default.bold("Email:  ") + config2.email);
-    console.log(source_default.bold("Org:    ") + config2.orgSlug);
+    const authSource = envKey ? "env" : "stored";
     try {
       const res = await apiRequest("/api/auth/whoami", {
-        headers: { Authorization: `Bearer ${config2.apiKey}` }
+        headers: { Authorization: `Bearer ${apiKey}` }
       });
-      if (res.user) {
-        console.log(source_default.bold("Role:   ") + res.user.role);
+      const payload = authIdentityPayload(authSource, res, envKey ? null : config2);
+      if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else {
+        printWhoami(payload);
       }
-      if (res.organization) {
-        console.log(source_default.bold("Name:   ") + res.organization.name);
+    } catch (err) {
+      if (config2 && !envKey) {
+        const payload = authIdentityPayload("stored", {}, config2, true);
+        if (options.json)
+          console.log(JSON.stringify(payload, null, 2));
+        else
+          printWhoami(payload);
+        return;
       }
-    } catch {
-      console.log(source_default.dim("(offline \u2014 showing cached info)"));
+      writeCommandError(err, "Failed to fetch current account", options.json);
     }
   });
   auth.command("status").description("Show hosted billing status").option("--json", "Output as JSON", false).action(handleBillingStatus);

package/bin/mcp.js

@@ -21819,7 +21819,7 @@ class StdioServerTransport {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.1.56",
+  version: "0.1.58",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -33056,6 +33056,16 @@ var pricingSchema = objectSchema({
   quoteDependsOnInput: { type: "boolean", description: "Whether input affects the quote." },
   quoteRequired: { type: "boolean", description: "Whether callers should quote before running." }
 }, [], "Public pricing metadata.");
+var skillAvailabilitySchema = objectSchema({
+  status: {
+    type: "string",
+    enum: ["available", "unavailable"],
+    description: "Whether hosted execution is currently available for this skill."
+  },
+  code: stringSchema("Optional stable unavailability code."),
+  message: stringSchema("Optional human-readable availability message."),
+  details: stringArraySchema("Optional availability details.")
+}, ["status"], "Hosted skill availability metadata.");
 var skillSummarySchema = objectSchema({
   name: stringSchema("Canonical skill slug."),
   category: stringSchema("Skill category."),
@@ -33411,7 +33421,14 @@ var toolContracts = [
     sideEffects: "none",
     stable: true,
     inputSchema: objectSchema({ name: skillNameInput, input: runInputSchema, args: runArgsSchema }, ["name"]),
-    outputSchema: objectSchema({ skill: stringSchema("Skill slug."), pricing: pricingSchema }, ["skill", "pricing"])
+    outputSchema: objectSchema({
+      skill: stringSchema("Skill slug."),
+      pricing: pricingSchema,
+      availability: skillAvailabilitySchema,
+      error: stringSchema("Optional error message when the quote cannot be used to run."),
+      code: stringSchema("Optional stable error code."),
+      details: stringArraySchema("Optional error details.")
+    }, ["skill", "pricing", "availability"])
   },
   {
     name: "run_skill",
@@ -34829,6 +34846,45 @@ function mimeForPath(path) {
       return "application/octet-stream";
   }
 }
+// src/lib/hosted-availability.ts
+init_skill_aliases();
+var UNAVAILABLE_HOSTED_PROVIDER_SKILLS = new Set([
+  "audio",
+  "brand-photo-shoot",
+  "browse",
+  "deepresearch",
+  "generate-book-cover",
+  "icon-pack",
+  "image",
+  "music",
+  "music-album",
+  "pdf-read",
+  "photo-album",
+  "playlist-maker",
+  "read-pdf",
+  "remove-background",
+  "short-video-pack",
+  "transcript",
+  "video",
+  "voiceover-jingle-pack",
+  "webcrawling"
+]);
+function getHostedRunAvailability(slug) {
+  const canonicalSlug = resolveSkillAlias(slug);
+  if (!UNAVAILABLE_HOSTED_PROVIDER_SKILLS.has(canonicalSlug)) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    status: 503,
+    code: "HOSTED_PROVIDER_UNAVAILABLE",
+    message: "hosted execution is temporarily unavailable for this skill",
+    details: [
+      "This skill requires a platform-managed execution path that is not enabled for live hosted runs yet.",
+      "No balance was charged."
+    ]
+  };
+}
 
 // src/mcp/operation-tools.ts
 function registerOperationTools(server) {
@@ -35045,9 +35101,33 @@ function registerOperationTools(server) {
         return mcpError("INVALID_BLOG_ARTICLE_OPTIONS", validation.errors.join(" "));
       }
     }
+    const pricing = getPublicSkillPricing2(skill.name, runInput, runArgs);
+    const hostedAvailability = getHostedRunAvailability(skill.name);
+    if (!hostedAvailability.ok) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            skill: skill.name,
+            pricing,
+            error: hostedAvailability.message,
+            code: hostedAvailability.code,
+            details: hostedAvailability.details,
+            availability: {
+              status: "unavailable",
+              code: hostedAvailability.code,
+              message: hostedAvailability.message,
+              details: hostedAvailability.details
+            }
+          })
+        }],
+        isError: true
+      };
+    }
     return mcpJson({
       skill: skill.name,
-      pricing: getPublicSkillPricing2(skill.name, runInput, runArgs)
+      pricing,
+      availability: { status: "available" }
     });
   });
   server.registerTool("run_skill", {
@@ -35090,6 +35170,18 @@ function registerOperationTools(server) {
       remote: isPremiumSkill2(skillName),
       costCents
     });
+    if (isPremiumSkill2(skillName)) {
+      const hostedAvailability = getHostedRunAvailability(skillName);
+      if (!hostedAvailability.ok) {
+        const error48 = `${hostedAvailability.code}: ${hostedAvailability.message}`;
+        writeRunLogs(runContext, "", `${error48}
+${hostedAvailability.details.join(`
+`)}
+`);
+        const run = completeSkillRun(runContext, { status: "failed", error: error48, costCents });
+        return mcpError(hostedAvailability.code, `${hostedAvailability.message}. ${hostedAvailability.details.join(" ")} Local run metadata: ${run.paths.runDir}/run.json`);
+      }
+    }
     if (isPremiumSkill2(skillName) && !apiKey) {
       const cost = formatCost2(costCents ?? 0);
       const error48 = `${skillName} is a hosted skill (${cost}). Run: skills setup --mode hosted && skills auth login`;

package/dist/index.js

@@ -18159,7 +18159,193 @@ function getApiUrl() {
   return normalizeSkillsApiOrigin(process.env.SKILLS_API_URL || loadConfig().apiUrl || "https://skills.md");
 }
 
+// src/lib/discovery.ts
+var VENDOR_TERMS = [
+  "Google Gemini",
+  "OpenAI Sora",
+  "MiniMax Hailuo",
+  "Claude Code",
+  "Claude Vision",
+  "DALL-E 3",
+  "GPT-4o Mini",
+  "Cerebras",
+  "OpenRouter",
+  "Firecrawl",
+  "ElevenLabs",
+  "Anthropic",
+  "OpenAI",
+  "Minimax",
+  "MiniMax",
+  "Gemini",
+  "Claude",
+  "Whisper",
+  "Seedance",
+  "Lyria",
+  "Sora",
+  "Veo",
+  "Exa.ai",
+  "Exa",
+  "XAI",
+  "xAI"
+];
+var VENDOR_TAGS = new Set([
+  "anthropic",
+  "cerebras",
+  "claude",
+  "exa",
+  "firecrawl",
+  "gemini",
+  "google",
+  "minimax",
+  "openai",
+  "openrouter",
+  "seedance",
+  "whisper",
+  "xai"
+]);
+var VENDOR_ENV_PREFIXES = [
+  "ANTHROPIC_",
+  "CEREBRAS_",
+  "EXA_",
+  "FIRECRAWL_",
+  "GEMINI_",
+  "GOOGLE_",
+  "MINIMAX_",
+  "OPENAI_",
+  "OPENROUTER_",
+  "XAI_"
+];
+var VENDOR_PACKAGE_PATTERNS = [
+  /anthropic/i,
+  /cerebras/i,
+  /exa/i,
+  /firecrawl/i,
+  /gemini/i,
+  /minimax/i,
+  /openai/i,
+  /openrouter/i,
+  /xai/i
+];
+var vendorPattern = new RegExp(`\\b(${VENDOR_TERMS.map(escapeRegExp).join("|")})\\b`, "gi");
+function getCompactSkillDiscovery(skill) {
+  return {
+    name: skill.name,
+    category: skill.category,
+    pricing: resolveDiscoveryPricing(skill)
+  };
+}
+function getPublicSkillDiscovery(skill) {
+  return {
+    ...skill,
+    description: sanitizePublicDiscoveryText(skill.description),
+    tags: publicDiscoveryTags(skill.tags),
+    pricing: resolveDiscoveryPricing(skill)
+  };
+}
+function publicDiscoveryPriceLabel(skill) {
+  return (skill.pricing ?? getPublicSkillPricing(skill.name)).formattedCost;
+}
+function publicDiscoveryTags(tags) {
+  return tags.filter((tag) => !VENDOR_TAGS.has(tag.toLowerCase()));
+}
+function sanitizePublicDiscoveryText(text) {
+  let sanitized = text.replace(vendorPattern, "hosted AI").replace(/\bLLM\b/g, "AI").replace(/\s{2,}/g, " ");
+  let previous;
+  do {
+    previous = sanitized;
+    sanitized = sanitized.replace(/\bhosted AI(?: providers)?\s*,\s*hosted AI(?: providers)?\b/gi, "hosted AI providers").replace(/\bhosted AI(?: providers)?\s*,?\s*and\s*hosted AI(?: providers)?\b/gi, "hosted AI providers").replace(/\bhosted AI(?: providers)?\s+or\s+hosted AI(?: providers)?\b/gi, "hosted AI providers").replace(/\bhosted AI providers\s+hosted AI\b/gi, "hosted AI providers").replace(/\bhosted AI providers\s+providers\b/gi, "hosted AI providers");
+  } while (sanitized !== previous);
+  return sanitized.trim();
+}
+function publicDiscoveryEnvVars(skillName, envVars) {
+  if (!isPremiumSkill(skillName))
+    return envVars;
+  const filtered = envVars.filter((envVar) => envVar !== "SKILL_API_KEY" && !VENDOR_ENV_PREFIXES.some((prefix) => envVar.startsWith(prefix)));
+  return filtered.includes("SKILLS_API_KEY") ? filtered : ["SKILLS_API_KEY", ...filtered];
+}
+function publicDiscoveryDependencies(skillName, dependencies) {
+  if (!isPremiumSkill(skillName))
+    return dependencies;
+  return Object.fromEntries(Object.entries(dependencies).filter(([name]) => !VENDOR_PACKAGE_PATTERNS.some((pattern) => pattern.test(name))));
+}
+function publicDiscoveryDocumentation(skill, documentation) {
+  if (!documentation)
+    return documentation;
+  if (!isPremiumSkill(skill.name))
+    return documentation;
+  return [
+    `# ${skill.displayName || skill.name}`,
+    sanitizePublicDiscoveryText(skill.description),
+    `Pricing: ${getPublicSkillPricing(skill.name).formattedCost}.`,
+    "Set `SKILLS_API_KEY` or run `skills auth login` for hosted runtime execution. Runtime routing and model selection are managed by the hosted Skills runtime."
+  ].join(`
+
+`);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function resolveDiscoveryPricing(skill) {
+  return skill.pricing && typeof skill.pricing.formattedCost === "string" ? skill.pricing : getPublicSkillPricing(skill.name);
+}
+
+// src/lib/hosted-availability.ts
+var UNAVAILABLE_HOSTED_PROVIDER_SKILLS = new Set([
+  "audio",
+  "brand-photo-shoot",
+  "browse",
+  "deepresearch",
+  "generate-book-cover",
+  "icon-pack",
+  "image",
+  "music",
+  "music-album",
+  "pdf-read",
+  "photo-album",
+  "playlist-maker",
+  "read-pdf",
+  "remove-background",
+  "short-video-pack",
+  "transcript",
+  "video",
+  "voiceover-jingle-pack",
+  "webcrawling"
+]);
+function getHostedRunAvailability(slug) {
+  const canonicalSlug = resolveSkillAlias(slug);
+  if (!UNAVAILABLE_HOSTED_PROVIDER_SKILLS.has(canonicalSlug)) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    status: 503,
+    code: "HOSTED_PROVIDER_UNAVAILABLE",
+    message: "hosted execution is temporarily unavailable for this skill",
+    details: [
+      "This skill requires a platform-managed execution path that is not enabled for live hosted runs yet.",
+      "No balance was charged."
+    ]
+  };
+}
+function getHostedAvailabilityMetadata(slug) {
+  const availability = getHostedRunAvailability(slug);
+  if (availability.ok)
+    return { status: "available" };
+  return {
+    status: "unavailable",
+    code: availability.code,
+    message: availability.message,
+    details: availability.details
+  };
+}
+
 // src/lib/remote-registry.ts
+var remoteAvailabilitySchema = exports_external.object({
+  status: exports_external.enum(["available", "unavailable"]),
+  code: exports_external.string().optional(),
+  message: exports_external.string().optional(),
+  details: exports_external.array(exports_external.string()).optional()
+}).passthrough();
 var remotePricingSchema = exports_external.object({
   formattedCost: exports_external.string(),
   tier: exports_external.string().optional(),
@@ -18181,10 +18367,22 @@ var remoteSkillSchema = exports_external.object({
   tags: exports_external.array(exports_external.string()).optional(),
   dependencies: exports_external.array(exports_external.string()).optional(),
   version: exports_external.string().optional(),
-  pricing: remotePricingSchema.optional()
+  pricing: remotePricingSchema.optional(),
+  availability: remoteAvailabilitySchema.optional()
 }).passthrough().refine((skill) => skill.name || skill.slug, {
   message: "Remote skill requires name or slug"
 });
+var secretValuePatterns = [
+  /\bsk-[A-Za-z0-9_-]{8,}\b/g,
+  /\bgh[opsur]_[A-Za-z0-9_]{8,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{8,}\b/g,
+  /\bnpm_[A-Za-z0-9_]{8,}\b/g,
+  /\bAKIA[A-Z0-9]{12,}\b/g,
+  /\bAIza[A-Za-z0-9_-]{10,}\b/g,
+  new RegExp("\\bsecret" + "-token:\\s*[A-Za-z0-9._-]+", "gi"),
+  /\bctx7sk\-[A-Za-z0-9_-]{8,}\b/g,
+  /\bxai\-[A-Za-z0-9_-]{8,}\b/g
+];
 var remoteSkillDetailSchema = exports_external.union([
   remoteSkillSchema,
   exports_external.object({ skill: remoteSkillSchema }),
@@ -18235,9 +18433,30 @@ function normalizeRemoteSkill(skill) {
     dependencies: skill.dependencies,
     ...skill.version ? { version: skill.version } : {},
     ...skill.pricing ? { pricing: skill.pricing } : {},
+    availability: normalizeRemoteAvailability(name, skill.availability),
     source: "remote"
   };
 }
+function normalizeRemoteAvailability(name, availability) {
+  if (!availability)
+    return getHostedAvailabilityMetadata(name);
+  if (availability.status === "available")
+    return { status: "available" };
+  return {
+    status: availability.status,
+    ...safeAvailabilityCode(availability.code) ? { code: safeAvailabilityCode(availability.code) } : {},
+    ...availability.message ? { message: sanitizeAvailabilityText(availability.message) } : {},
+    ...availability.details ? { details: availability.details.map(sanitizeAvailabilityText).filter(Boolean) } : {}
+  };
+}
+function safeAvailabilityCode(code) {
+  if (!code)
+    return;
+  return /^[A-Z0-9_]+$/.test(code) ? code : undefined;
+}
+function sanitizeAvailabilityText(text) {
+  return secretValuePatterns.reduce((value, pattern) => value.replace(pattern, "credential"), sanitizePublicDiscoveryText(text).replace(/\b[A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|CREDENTIAL)[A-Z0-9_]*\b/g, "credential")).replace(/\s{2,}/g, " ").trim();
+}
 function parseRemoteRegistryPayload(payload) {
   const parsed = parseRemoteContract(remoteRegistrySchema, payload, "Remote registry payload did not match the expected skills contract");
   const rawSkills = Array.isArray(parsed) ? parsed : ("skills" in parsed) ? parsed.skills : parsed.data;
@@ -18299,135 +18518,6 @@ async function loadRemoteSkill(name, options = {}) {
   const url2 = buildSkillsApiUrl(apiUrl, options.endpoint ?? `/skills/${slug}`);
   return parseRemoteSkillPayload(await fetchRemoteJson(url2, options));
 }
-// src/lib/discovery.ts
-var VENDOR_TERMS = [
-  "Google Gemini",
-  "OpenAI Sora",
-  "MiniMax Hailuo",
-  "Claude Code",
-  "Claude Vision",
-  "DALL-E 3",
-  "GPT-4o Mini",
-  "Cerebras",
-  "OpenRouter",
-  "Firecrawl",
-  "ElevenLabs",
-  "Anthropic",
-  "OpenAI",
-  "Minimax",
-  "MiniMax",
-  "Gemini",
-  "Claude",
-  "Whisper",
-  "Seedance",
-  "Lyria",
-  "Sora",
-  "Veo",
-  "Exa.ai",
-  "Exa",
-  "XAI",
-  "xAI"
-];
-var VENDOR_TAGS = new Set([
-  "anthropic",
-  "cerebras",
-  "claude",
-  "exa",
-  "firecrawl",
-  "gemini",
-  "google",
-  "minimax",
-  "openai",
-  "openrouter",
-  "seedance",
-  "whisper",
-  "xai"
-]);
-var VENDOR_ENV_PREFIXES = [
-  "ANTHROPIC_",
-  "CEREBRAS_",
-  "EXA_",
-  "FIRECRAWL_",
-  "GEMINI_",
-  "GOOGLE_",
-  "MINIMAX_",
-  "OPENAI_",
-  "OPENROUTER_",
-  "XAI_"
-];
-var VENDOR_PACKAGE_PATTERNS = [
-  /anthropic/i,
-  /cerebras/i,
-  /exa/i,
-  /firecrawl/i,
-  /gemini/i,
-  /minimax/i,
-  /openai/i,
-  /openrouter/i,
-  /xai/i
-];
-var vendorPattern = new RegExp(`\\b(${VENDOR_TERMS.map(escapeRegExp).join("|")})\\b`, "gi");
-function getCompactSkillDiscovery(skill) {
-  return {
-    name: skill.name,
-    category: skill.category,
-    pricing: resolveDiscoveryPricing(skill)
-  };
-}
-function getPublicSkillDiscovery(skill) {
-  return {
-    ...skill,
-    description: sanitizePublicDiscoveryText(skill.description),
-    tags: publicDiscoveryTags(skill.tags),
-    pricing: resolveDiscoveryPricing(skill)
-  };
-}
-function publicDiscoveryPriceLabel(skill) {
-  return (skill.pricing ?? getPublicSkillPricing(skill.name)).formattedCost;
-}
-function publicDiscoveryTags(tags) {
-  return tags.filter((tag) => !VENDOR_TAGS.has(tag.toLowerCase()));
-}
-function sanitizePublicDiscoveryText(text) {
-  let sanitized = text.replace(vendorPattern, "hosted AI").replace(/\bLLM\b/g, "AI").replace(/\s{2,}/g, " ");
-  let previous;
-  do {
-    previous = sanitized;
-    sanitized = sanitized.replace(/\bhosted AI(?: providers)?\s*,\s*hosted AI(?: providers)?\b/gi, "hosted AI providers").replace(/\bhosted AI(?: providers)?\s*,?\s*and\s*hosted AI(?: providers)?\b/gi, "hosted AI providers").replace(/\bhosted AI(?: providers)?\s+or\s+hosted AI(?: providers)?\b/gi, "hosted AI providers").replace(/\bhosted AI providers\s+hosted AI\b/gi, "hosted AI providers").replace(/\bhosted AI providers\s+providers\b/gi, "hosted AI providers");
-  } while (sanitized !== previous);
-  return sanitized.trim();
-}
-function publicDiscoveryEnvVars(skillName, envVars) {
-  if (!isPremiumSkill(skillName))
-    return envVars;
-  const filtered = envVars.filter((envVar) => envVar !== "SKILL_API_KEY" && !VENDOR_ENV_PREFIXES.some((prefix) => envVar.startsWith(prefix)));
-  return filtered.includes("SKILLS_API_KEY") ? filtered : ["SKILLS_API_KEY", ...filtered];
-}
-function publicDiscoveryDependencies(skillName, dependencies) {
-  if (!isPremiumSkill(skillName))
-    return dependencies;
-  return Object.fromEntries(Object.entries(dependencies).filter(([name]) => !VENDOR_PACKAGE_PATTERNS.some((pattern) => pattern.test(name))));
-}
-function publicDiscoveryDocumentation(skill, documentation) {
-  if (!documentation)
-    return documentation;
-  if (!isPremiumSkill(skill.name))
-    return documentation;
-  return [
-    `# ${skill.displayName || skill.name}`,
-    sanitizePublicDiscoveryText(skill.description),
-    `Pricing: ${getPublicSkillPricing(skill.name).formattedCost}.`,
-    "Set `SKILLS_API_KEY` or run `skills auth login` for hosted runtime execution. Runtime routing and model selection are managed by the hosted Skills runtime."
-  ].join(`
-
-`);
-}
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function resolveDiscoveryPricing(skill) {
-  return skill.pricing && typeof skill.pricing.formattedCost === "string" ? skill.pricing : getPublicSkillPricing(skill.name);
-}
 // src/lib/tool-primitives.ts
 var TOOL_PRIMITIVE_SCHEMA_VERSION = 1;
 var TOOL_PRIMITIVES = [
@@ -19265,7 +19355,7 @@ import { dirname as dirname4, relative as relative3 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.1.56",
+  version: "0.1.58",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -19491,6 +19581,16 @@ var pricingSchema = objectSchema({
   quoteDependsOnInput: { type: "boolean", description: "Whether input affects the quote." },
   quoteRequired: { type: "boolean", description: "Whether callers should quote before running." }
 }, [], "Public pricing metadata.");
+var skillAvailabilitySchema = objectSchema({
+  status: {
+    type: "string",
+    enum: ["available", "unavailable"],
+    description: "Whether hosted execution is currently available for this skill."
+  },
+  code: stringSchema("Optional stable unavailability code."),
+  message: stringSchema("Optional human-readable availability message."),
+  details: stringArraySchema("Optional availability details.")
+}, ["status"], "Hosted skill availability metadata.");
 var skillSummarySchema = objectSchema({
   name: stringSchema("Canonical skill slug."),
   category: stringSchema("Skill category."),
@@ -19846,7 +19946,14 @@ var toolContracts = [
     sideEffects: "none",
     stable: true,
     inputSchema: objectSchema({ name: skillNameInput, input: runInputSchema, args: runArgsSchema }, ["name"]),
-    outputSchema: objectSchema({ skill: stringSchema("Skill slug."), pricing: pricingSchema }, ["skill", "pricing"])
+    outputSchema: objectSchema({
+      skill: stringSchema("Skill slug."),
+      pricing: pricingSchema,
+      availability: skillAvailabilitySchema,
+      error: stringSchema("Optional error message when the quote cannot be used to run."),
+      code: stringSchema("Optional stable error code."),
+      details: stringArraySchema("Optional error details.")
+    }, ["skill", "pricing", "availability"])
   },
   {
     name: "run_skill",

package/dist/lib/hosted-availability.d.ts

@@ -0,0 +1,13 @@
+import type { SkillAvailabilityMetadata } from "./registry-types.js";
+export interface HostedRunUnavailable {
+    ok: false;
+    status: 503;
+    code: "HOSTED_PROVIDER_UNAVAILABLE";
+    message: string;
+    details: string[];
+}
+export type HostedRunAvailability = {
+    ok: true;
+} | HostedRunUnavailable;
+export declare function getHostedRunAvailability(slug: string): HostedRunAvailability;
+export declare function getHostedAvailabilityMetadata(slug: string): SkillAvailabilityMetadata;

package/dist/lib/registry-types.d.ts

@@ -7,6 +7,7 @@ export interface SkillMeta {
     dependencies?: string[];
     version?: string;
     pricing?: SkillPricingMetadata;
+    availability?: SkillAvailabilityMetadata;
     source?: "official" | "custom" | "remote";
 }
 export interface SkillPricingMetadata {
@@ -21,6 +22,12 @@ export interface SkillPricingMetadata {
     quoteRequired?: boolean;
     description?: string;
 }
+export interface SkillAvailabilityMetadata {
+    status: "available" | "unavailable";
+    code?: string;
+    message?: string;
+    details?: string[];
+}
 export declare const CATEGORIES: readonly ["Development Tools", "Business & Marketing", "Productivity & Organization", "Project Management", "Content Generation", "Finance & Compliance", "Data & Analysis", "Media Processing", "Design & Branding", "Web & Browser", "Research & Writing", "Science & Academic", "Education & Learning", "Communication", "Health & Wellness", "Travel & Lifestyle", "Event Management"];
 export type Category = (typeof CATEGORIES)[number];
 export declare const BASIC_SKILL_NAMES: readonly ["image", "video", "audio", "music", "transcript", "audio-extract", "read-image", "read-pdf", "pdf-read", "pdf-to-markdown", "doc-read", "pdf-generate", "doc-generate", "read-csv", "read-excel", "excel", "convert"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {