@relvo/mcp 0.1.4 → 0.1.6

package/dist/mcp/update-notice.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+const SETTLING_MS = 72 * 60 * 60 * 1000;
+const METADATA_LIMIT = 1024 * 1024;
+const packumentSchema = z.object({
+    "dist-tags": z.object({ latest: z.string() }),
+    time: z.record(z.string(), z.string()),
+    versions: z.record(z.string(), z.object({ deprecated: z.unknown().optional() })),
+});
+const RELEASE_MANIFEST_URL = "https://app.relvo.si/relvo/cli-releases.json";
+const manifestSchema = z.object({ releases: z.record(z.string(), z.string()) });
+const parseVersion = (value) => /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value) ? value.split(".").map(Number) : undefined;
+const isNewer = (candidate, than) => {
+    const left = parseVersion(candidate), right = parseVersion(than);
+    if (!left || !right)
+        return false;
+    const index = left.findIndex((part, position) => part !== right[position]);
+    return index >= 0 && left[index] > right[index];
+};
+const readDocument = async (url, transport) => {
+    const response = await transport(url, { headers: { accept: "application/json" }, redirect: "error", credentials: "omit", signal: AbortSignal.timeout(3000) });
+    if (!response.ok)
+        return undefined;
+    const text = await response.text();
+    return text.length > METADATA_LIMIT ? undefined : JSON.parse(text);
+};
+export async function settledRelease(packageName, transport, now) {
+    const [packument, manifest] = await Promise.all([readDocument(`https://registry.npmjs.org/${packageName.replace("/", "%2f")}`, transport), readDocument(RELEASE_MANIFEST_URL, transport)]);
+    if (!packument || !manifest)
+        return undefined;
+    const { "dist-tags": { latest }, time, versions } = packumentSchema.parse(packument), { releases } = manifestSchema.parse(manifest);
+    let best;
+    for (const [version, entry] of Object.entries(versions)) {
+        const published = Date.parse(time[version] ?? "");
+        if (!parseVersion(version) || !Object.hasOwn(releases, version) || isNewer(version, latest) || entry.deprecated || !(published <= now - SETTLING_MS))
+            continue;
+        if (!best || isNewer(version, best))
+            best = version;
+    }
+    return best;
+}
+export function startUpdateCheck(running, managed, transport = fetch, now = Date.now()) {
+    let notice;
+    settledRelease(managed ? "@relvo/cli" : "@relvo/mcp", transport, now).then((release) => {
+        if (!release || !isNewer(release, running))
+            return;
+        notice = `Relvo update available. Tell the user in your reply: this session runs ${running}, and ${release} is released. To update, `
+            + (managed ? "run `npx --yes @relvo/cli update` in a terminal, then restart this MCP client."
+                : `set @relvo/mcp@${release} in this MCP client's configuration, then restart it.`);
+    }).catch(() => { });
+    return () => {
+        const shown = notice;
+        notice = undefined;
+        return shown;
+    };
+}
+export function withUpdateNotice(notice, handler) {
+    return async (...args) => {
+        const result = await handler(...args);
+        const content = "content" in result ? result.content : undefined;
+        const text = Array.isArray(content) ? notice?.() : undefined;
+        if (!text || !Array.isArray(content))
+            return result;
+        const structured = "structuredContent" in result ? result.structuredContent : undefined;
+        return { ...result, content: [...content, { type: "text", text, annotations: { audience: ["user", "assistant"] } }],
+            ...(structured ? { structuredContent: { ...structured, relvoUpdate: text } } : {}) };
+    };
+}

package/dist/mcp/version.js

@@ -1 +1 @@
-export const PLATFORM_MCP_VERSION = "0.1.3";
+export const PLATFORM_MCP_VERSION = "0.1.5";

package/dist/schema/platformCapabilityFamilies.js

@@ -201,8 +201,8 @@ const variants = {
         "serpapi_google_ads_transparency_center"],
     search_google_ads_transparency_details: ["anyapi_google_ads_ad_details", "searchapi_google_ads_transparency_center_ad_details",
         "serpapi_google_ads_transparency_center_ad_details"],
-    search_linkedin_ads_library: ["anyapi_linkedin_ads_search", "anyapi_linkedin_ad", "searchapi_linkedin_ad_library",
-        "searchapi_linkedin_ad_library_ad_details"],
+    search_linkedin_ads_library: ["anyapi_linkedin_ads_search", "searchapi_linkedin_ad_library"],
+    get_linkedin_ad_details: ["anyapi_linkedin_ad", "searchapi_linkedin_ad_library_ad_details"],
     search_tiktok_ads_library: ["anyapi_tiktok_ad_library_search", "searchapi_tiktok_ads_library"],
     search_tiktok_ads_library_details: ["anyapi_tiktok_ad_library_ad", "searchapi_tiktok_ads_library_ad_details"],
     search_mobile_apps: ["dataforseo_app_data_apple_app_searches_advanced", "dataforseo_app_data_google_app_searches_advanced", "dataforseo_app_data_google_app_searches_html",
@@ -262,8 +262,29 @@ const additions = {
         "scrapecreators_v1_facebook_ad_library_company_ads", "scrapecreators_v1_facebook_ad_library_company_ads_post"],
     search_google_ads_transparency: ["scrapecreators_v1_google_company_ads"],
     search_google_ads_transparency_details: ["scrapecreators_v1_google_ad"],
-    search_linkedin_ads_library: ["scrapecreators_v1_linkedin_ads_search", "scrapecreators_v1_linkedin_ad"],
+    search_linkedin_ads_library: ["scrapecreators_v1_linkedin_ads_search"],
+    get_linkedin_ad_details: ["scrapecreators_v1_linkedin_ad"],
+    search_meta_ad_library_details: ["scrapecreators_v1_facebook_ad_library_ad"],
     search_meta_ad_library_pages: ["scrapecreators_v1_facebook_ad_library_search_companies"],
     search_tiktok_ads_library: ["scrapecreators_v1_tiktok_ad_library_search"],
+    get_tiktok_audience: ["anyapi_tiktok_audience_demographics", "scrapecreators_v1_tiktok_user_audience"],
+    get_tiktok_account_network: ["anyapi_tiktok_followers", "anyapi_tiktok_following", "tikhub_tiktok_app_v3_fetch_user_follower_list", "tikhub_tiktok_app_v3_fetch_user_following_list",
+        "tikhub_tiktok_web_fetch_user_fans", "tikhub_tiktok_web_fetch_user_follow", "scrapecreators_v1_tiktok_user_followers", "scrapecreators_v1_tiktok_user_following"],
+    get_youtube_video_sponsors: ["anyapi_youtube_video_sponsors", "scrapecreators_v1_youtube_video_sponsors"],
+    get_youtube_playlist: ["anyapi_youtube_playlist", "scrapecreators_v1_youtube_playlist", "searchapi_youtube_playlist"],
+    get_youtube_channel_playlists: ["anyapi_youtube_channel_playlists", "scrapecreators_v1_youtube_channel_playlists"],
+    get_instagram_trending_reels: ["anyapi_instagram_trending_reels", "scrapecreators_v1_instagram_reels_trending"],
+    get_youtube_trending_shorts: ["anyapi_youtube_trending_shorts", "scrapecreators_v1_youtube_shorts_trending"],
+    get_social_post_transcript: ["anyapi_facebook_post_transcript", "anyapi_linkedin_post_transcript", "anyapi_twitter_tweet_transcript", "anyapi_reddit_post_transcript",
+        "anyapi_instagram_media_transcript", "scrapecreators_v1_facebook_post_transcript", "scrapecreators_v1_linkedin_post_transcript", "scrapecreators_v1_twitter_tweet_transcript",
+        "scrapecreators_v1_reddit_post_transcript", "scrapecreators_v2_instagram_media_transcript"],
+    get_linkedin_company: ["anyapi_linkedin_company", "tikhub_linkedin_web_v2_get_company_profile", "scrapecreators_v1_linkedin_company", "brightdata_linkedin_companies_collect_by_url"],
+    get_linkedin_company_posts: ["anyapi_linkedin_company_posts", "anyapi_linkedin_company_posts_thin", "tikhub_linkedin_web_v2_get_company_posts", "scrapecreators_v1_linkedin_company_posts",
+        "brightdata_linkedin_posts_discover_by_company_url"],
+    read_link_in_bio: ["anyapi_linktree_profile", "scrapecreators_v1_linktree", "scrapecreators_v1_linkme", "scrapecreators_v1_komi", "scrapecreators_v1_pillar", "scrapecreators_v1_linkbio"],
+    get_facebook_post_comments: ["anyapi_facebook_post_comments", "scrapecreators_v1_facebook_post_comments", "brightdata_facebook_comments_collect_by_url"],
+    get_facebook_group_posts: ["anyapi_facebook_group_posts", "scrapecreators_v1_facebook_group_posts", "brightdata_facebook_posts_by_group_collect_by_url"],
+    find_creator_emails: ["scrapecreators_v1_find_creator_emails"],
+    find_creator_social_profiles: ["scrapecreators_v1_find_social_profiles"],
 };
-export const AUTO_CAPABILITY_VARIANTS = Object.fromEntries(Object.keys({ ...variants, ...additions }).map(name => [name, [...variants[name] ?? [], ...additions[name] ?? []]]));
+export const AUTO_CAPABILITY_VARIANTS = Object.fromEntries(Object.keys({ ...variants, ...additions }).map(name => [name, [...(variants[name] ?? []), ...(additions[name] ?? [])]]));

package/dist/schema/platformCustomTools.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { projectScopeSchema, platformJsonObjectSchema, PLATFORM_SANDBOX_LIMITS } from "./platformPublicExecution.js";
-import { PLATFORM_APP_HOST_PATTERN, PLATFORM_APP_RESERVED_HEADERS } from "./platformHttpConstraints.js";
+import { isPlatformCallerHeaderName, isPlatformHeaderValue, PLATFORM_APP_HOST_PATTERN, PLATFORM_APP_RESERVED_HEADERS } from "./platformHttpConstraints.js";
 import { platformTeamSecretNameSchema } from "./platformTeamSecretName.js";
 export const PLATFORM_CUSTOM_TOOL_PREFIX = "custom__";
 export const PLATFORM_CUSTOM_TOOL_LIMITS = {
@@ -12,7 +12,7 @@ export const PLATFORM_CUSTOM_TOOL_LIMITS = {
     schemaBytes: 16_384,
     inputBytes: 16_384,
 };
-export const PLATFORM_CUSTOM_ENDPOINT_LIMITS = { bindings: 5, baseUrlChars: 2_048, nameChars: 64, templateChars: 256, secretChars: 4_096 };
+export const PLATFORM_CUSTOM_ENDPOINT_LIMITS = { bindings: 5, baseUrlChars: 2_048, nameChars: 64, templateChars: 256, secretChars: 4_096, headers: 10, query: 10, valueChars: 1_024 };
 export const platformCustomToolKindSchema = z.enum(["python", "http"]);
 export const platformCustomEndpointLocationSchema = z.enum(["header", "query"]);
 const HEADER_NAME = /^[A-Za-z0-9_-]{1,64}$/;
@@ -53,8 +53,22 @@ export const platformCustomEndpointBindingInputSchema = z.object({
     .refine(binding => binding.secret === undefined || binding.secretRef === undefined, "A binding takes a secret or a secretRef, not both");
 export const platformCustomEndpointBindingSchema = z.object({ id: z.string(), location: bindingLocation, name: bindingName, template: bindingTemplateSchema,
     maskedSecret: z.string().nullable(), secretRef: platformTeamSecretNameSchema.nullable().default(null) }).strict();
+export const isPlatformCustomEndpointFixedName = (location, name) => location === "header"
+    ? isPlatformCallerHeaderName(name) && !/^(?:keep-alive|trailer)$/i.test(name)
+    : name.length >= 1 && name.length <= PLATFORM_CUSTOM_ENDPOINT_LIMITS.nameChars && !CONTROL.test(name);
+export const isPlatformCustomEndpointFixedValue = (location, value) => value.length >= 1 && value.length <= PLATFORM_CUSTOM_ENDPOINT_LIMITS.valueChars
+    && !CONTROL.test(value) && (location === "query" || isPlatformHeaderValue(value));
+const fixedValuesSchema = (location) => z.record(z.string(), z.string())
+    .refine(values => Object.keys(values).length <= PLATFORM_CUSTOM_ENDPOINT_LIMITS[location === "header" ? "headers" : "query"], "Too many fixed values")
+    .refine(values => Object.entries(values).every(([name, value]) => isPlatformCustomEndpointFixedName(location, name) && isPlatformCustomEndpointFixedValue(location, value)), `${location === "header" ? "A header a caller may set" : "A name without control characters"}, with a value of 1–${PLATFORM_CUSTOM_ENDPOINT_LIMITS.valueChars} characters that can be sent`)
+    .refine(values => new Set(Object.keys(values).map(name => name.toLowerCase())).size === Object.keys(values).length, "Each name once, in any case");
+export const platformCustomEndpointHeadersSchema = fixedValuesSchema("header")
+    .describe("Fixed, non-secret headers Relvo adds to every request, e.g. {\"X-Api-Version\":\"2024-06-01\"}; anyone who can read the tool sees them, so a credential goes in a binding. A request that sets one of these names is refused.");
+export const platformCustomEndpointQuerySchema = fixedValuesSchema("query")
+    .describe("Fixed, non-secret query parameters Relvo adds to every request, e.g. {\"format\":\"json\"}; anyone who can read the tool sees them, so a credential goes in a binding. A request that sets one of these names is refused.");
 export const platformCustomEndpointSchema = z.object({ baseUrl: platformCustomEndpointBaseUrlSchema,
-    bindings: z.array(platformCustomEndpointBindingSchema).min(1).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.bindings) }).strict();
+    headers: platformCustomEndpointHeadersSchema.optional(), query: platformCustomEndpointQuerySchema.optional(),
+    bindings: z.array(platformCustomEndpointBindingSchema).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.bindings) }).strict();
 export const platformCustomToolSlugSchema = z.string().regex(/^[a-z][a-z0-9_]{1,39}$/)
     .describe("Lowercase letters, digits and underscores, starting with a letter; the tool is named custom__<slug>.");
 export const PLATFORM_CUSTOM_TOOL_NAME = /^custom__[a-z][a-z0-9_]{1,39}$/;
@@ -79,14 +93,20 @@ export const platformCustomEndpointDefinitionSchema = z.object({
     title: z.string().trim().min(1).max(PLATFORM_CUSTOM_TOOL_LIMITS.titleChars),
     description: z.string().trim().min(1).max(PLATFORM_CUSTOM_TOOL_LIMITS.descriptionChars).describe("What the API is and when to use it; agents choose tools by it."),
     baseUrl: platformCustomEndpointBaseUrlSchema,
-    bindings: z.array(platformCustomEndpointBindingInputSchema).min(1).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.bindings).refine(uniqueBindings, "Each header or query parameter is bound once")
-        .describe("Credentials Relvo adds to every request, in the header or query parameter named. Agents never see them."),
+    headers: platformCustomEndpointHeadersSchema.optional(),
+    query: platformCustomEndpointQuerySchema.optional(),
+    bindings: z.array(platformCustomEndpointBindingInputSchema).max(PLATFORM_CUSTOM_ENDPOINT_LIMITS.bindings).refine(uniqueBindings, "Each header or query parameter is bound once").default([])
+        .describe("Credentials Relvo adds to every request, in the header or query parameter named. Agents never see them. Empty for an API that needs none."),
     enabled: z.boolean().default(true),
 }).strict();
+const fixedApartFromBindings = (endpoint) => endpoint.bindings.every(binding => !Object.keys((binding.location === "header" ? endpoint.headers : endpoint.query) ?? {}).some(name => name.toLowerCase() === binding.name.toLowerCase()));
+const apart = { message: "A header or query parameter is either fixed or bound, not both", path: ["bindings"] };
 const slugged = { slug: platformCustomToolSlugSchema };
 const versioned = { expectedVersion: z.number().int().min(1) };
-export const platformCustomToolCreateSchema = z.union([platformCustomToolDefinitionSchema.extend(slugged).strict(), platformCustomEndpointDefinitionSchema.extend(slugged).strict()]);
-export const platformCustomToolUpdateSchema = z.union([platformCustomToolDefinitionSchema.extend(versioned).strict(), platformCustomEndpointDefinitionSchema.extend(versioned).strict()]);
+export const platformCustomToolCreateSchema = z.union([platformCustomToolDefinitionSchema.extend(slugged).strict(),
+    platformCustomEndpointDefinitionSchema.extend(slugged).strict().refine(fixedApartFromBindings, apart)]);
+export const platformCustomToolUpdateSchema = z.union([platformCustomToolDefinitionSchema.extend(versioned).strict(),
+    platformCustomEndpointDefinitionSchema.extend(versioned).strict().refine(fixedApartFromBindings, apart)]);
 export const platformCustomToolRestoreSchema = z.object({ version: z.number().int().min(1), expectedVersion: z.number().int().min(1) }).strict();
 export const platformCustomToolSchema = z.object({
     kind: platformCustomToolKindSchema.default("python"), endpoint: platformCustomEndpointSchema.nullable().default(null),

package/dist/schema/platformHttpConstraints.js

@@ -2,6 +2,10 @@ import { z } from "zod";
 import { ACCOUNT_REQUEST_HTTP_METHODS } from "./accountRequestMethods.js";
 export const PLATFORM_APP_HOST_PATTERN = /^(?=[^:]{4,253}(?::|$))(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9](?::[1-9][0-9]{0,4})?$/;
 export const PLATFORM_APP_RESERVED_HEADERS = new Set(["host", "cookie", "content-length", "transfer-encoding", "connection", "proxy-authorization", "forwarded", "te", "upgrade", "expect"]);
+export const PLATFORM_CREDENTIAL_HEADER = /^(?:authorization|x-api-key|api-key|apikey|x-auth-token|x-access-token|cookie|set-cookie|proxy-.*|x-forwarded-.*|x-real-ip)$/i;
+export const isPlatformCallerHeaderName = (name) => /^[A-Za-z0-9_-]{1,64}$/.test(name) && !PLATFORM_APP_RESERVED_HEADERS.has(name.toLowerCase())
+    && !PLATFORM_CREDENTIAL_HEADER.test(name) && !/^(?:x-http-method-override|x-http-method|x-method-override)$/i.test(name);
+export const isPlatformHeaderValue = (value) => !/[\r\n\u0000]|[^\x00-\xff]/.test(value);
 export const platformAppApiPathSchema = z.object({ baseUrl: z.number().int().min(0).max(8), method: z.enum(ACCOUNT_REQUEST_HTTP_METHODS),
     path: z.string().startsWith("/").max(2048).refine(path => !/[?#\\\s\u0000-\u001f]/.test(path) && !path.includes("//")
         && path.split("/").every(segment => segment !== "." && segment !== ".." && (!/[{}]/.test(segment) || /^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(segment)))) }).strict();

package/dist/schema/platformLocalSetup.js

@@ -22,4 +22,4 @@ export const platformLocalSetupPollSchema = z.discriminatedUnion("status", [
 export const platformLocalSetupMetadataSchema = z.object({ client: platformLocalSetupClientSchema,
     expiresAt: z.iso.datetime(), status: z.enum(["pending", "approved", "acknowledged"]),
     apiKeyId: z.string().optional(), developerOrganizationId: z.string().optional(), developerProjectId: z.string().optional(),
-    scopes: z.array(developerKeyScopeSchema).optional(), approvedExpiresAt: z.iso.datetime().optional() }).strict();
+    scopes: z.array(developerKeyScopeSchema).optional(), approvedExpiresAt: z.iso.datetime().optional(), requestedFrom: z.string().optional() }).strict();

package/dist/schema/platformMetaTools.js

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import { platformCatalogSchema, platformCreateExecutionSchema, platformExecutionIdSchema, platformExecutionStatusSchema, platformMicrosSchema, platformQuoteSchema, platformToolNameSchema, platformToolSessionIdSchema, platformOptionalToolSessionIdSchema, PLATFORM_SANDBOX_LIMITS, platformExecutionSchema, platformExecutionContextSchema, platformRequestIntentSchema, validatePlatformArgumentIdentifiers } from "./platformPublicExecution.js";
+import { platformCatalogSchema, platformCreateExecutionSchema, platformExecutionIdSchema, platformExecutionStatusSchema, platformMicrosSchema, platformQuoteSchema, platformToolNameSchema, platformToolSessionIdSchema, platformOptionalToolSessionIdSchema, PLATFORM_SANDBOX_LIMITS, platformExecutionSchema, platformExecutionContextSchema, platformRequestIntentSchema, validatePlatformArgumentIdentifiers, PLATFORM_TOOL_REQUEST_MAX_BYTES } from "./platformPublicExecution.js";
 import { platformAnyConnectionProviderSchema, platformConnectionCatalogSchema } from "./platformConnectionCatalog.js";
 import { toolDiscoveryInputSchema, toolDiscoveryResultSchema } from "./toolDiscovery.js";
 export { PLATFORM_MCP_DIRECT_TOOLS_MAX, platformMcpDirectToolNames } from "./platformMcpTools.js";
 export const PLATFORM_META_LIMITS = { queries: 4, schemas: 12, batch: 50, concurrency: 4, contextBytes: 24_000,
-    requestBytes: 1_048_576, requestTimeoutMs: 90_000, sessionLifetimeMs: 86_400_000, activeSessions: 100,
+    requestBytes: PLATFORM_TOOL_REQUEST_MAX_BYTES, requestTimeoutMs: 90_000, sessionLifetimeMs: 86_400_000, activeSessions: 100,
     codeChars: PLATFORM_SANDBOX_LIMITS.code, commandChars: 16_000, sourceExecutions: PLATFORM_SANDBOX_LIMITS.sourceExecutions, timeoutMs: PLATFORM_SANDBOX_LIMITS.timeoutMs };
 export const isSessionSandboxTool = (name) => name === "remote_workbench" || name === "remote_bash";
 export const platformToolSessionSchema = z.object({ id: platformToolSessionIdSchema, expiresAt: z.iso.datetime(),

package/dist/schema/platformPublicExecution.js

@@ -5,6 +5,7 @@ export const PLATFORM_EXECUTION_MAX_STEPS = 20;
 export const PLATFORM_EXECUTION_MAX_WAIT_SECONDS = 25;
 export const PLATFORM_STEP_OUTPUT_MAX_BYTES = 1_048_576;
 export const PLATFORM_EXECUTION_RESPONSE_MAX_BYTES = PLATFORM_EXECUTION_MAX_STEPS * PLATFORM_STEP_OUTPUT_MAX_BYTES + 65_536;
+export const PLATFORM_TOOL_REQUEST_MAX_BYTES = 1_048_576;
 export const platformJsonObjectSchema = z.record(z.string(), z.json());
 export const organizationScopeSchema = z.object({ developerOrganizationId: z.string().min(1).max(128) });
 export const projectScopeSchema = organizationScopeSchema.extend({ developerProjectId: z.string().min(1).max(128) });
@@ -148,7 +149,8 @@ export const platformArtifactSchema = z.object({
     sizeBytes: z.number().int().positive().max(64 * 1024 * 1024), sha256: z.string().regex(/^[a-f0-9]{64}$/),
     generation: z.string().regex(/^\d{1,30}$/), expiresAt: z.iso.datetime(),
 });
-export const platformArtifactDownloadSchema = z.object({ url: z.url().refine((value) => { const url = new URL(value); return url.protocol === "https:" && !url.username && !url.password; }), expiresAt: z.iso.datetime() });
+export const platformArtifactDownloadSchema = z.object({ url: z.url().refine((value) => { if (!URL.canParse(value))
+        return false; const url = new URL(value); return url.protocol === "https:" && !url.username && !url.password; }), expiresAt: z.iso.datetime() });
 export const platformUnavailableReasonSchema = z.enum(["setup", "own_key", "connection", "permission", "retired"]);
 export const platformCatalogToolSchema = z.object({
     name: platformToolNameSchema, title: z.string().optional(), description: z.string(), category: z.enum(["research", "seo", "social", "generation", "enrichment", "finance", "news"]),

package/dist/schema/platformTeamSkills.js

@@ -1,13 +1,246 @@
 import { z } from "zod";
+import { Document, isScalar, parseDocument, visit } from "yaml";
 import { projectScopeSchema } from "./platformPublicExecution.js";
 import { PLATFORM_CUSTOM_TOOL_LIMITS, platformVersionAuthorSchema } from "./platformCustomTools.js";
 export const PLATFORM_TEAM_SKILL_LIMITS = {
     perProject: 200,
     versions: 50,
     titleChars: 80,
-    descriptionChars: 500,
+    descriptionChars: 1024,
     contentBytes: 32_768,
+    markdownBytes: 65_536,
+    files: 200,
+    fileBytes: 5 * 1024 * 1024,
+    packageBytes: 10 * 1024 * 1024,
+    requestBytes: 20 * 1024 * 1024,
 };
+export const PLATFORM_TEAM_STORAGE_BYTES = 100_000_000;
+export const platformSkillStorageSchema = z.object({ usedBytes: z.number().int().nonnegative().safe(), limitBytes: z.number().int().positive().safe() });
+export const platformSkillPathSchema = z.string().min(1).max(260).refine(path => !/[\\\u0000-\u001f\u007f:]/u.test(path.normalize("NFKC")) && !path.startsWith("/") && path.normalize("NFKC").split("/").every(part => part && !/[. ]$/.test(part)
+    && ![".git", "node_modules", "__proto__", "constructor", "prototype"].includes(part.toLowerCase()) && !/^\.env(?:\.|$)/i.test(part)
+    && !/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)), "Invalid relative skill file path");
+export const platformSkillFilePathSchema = platformSkillPathSchema.refine(path => path.normalize("NFKC").toLowerCase() !== "skill.md", "SKILL.md is the main skill content");
+export const platformSkillFileSchema = z.object({
+    path: platformSkillFilePathSchema,
+    data: z.string().max(Math.ceil(PLATFORM_TEAM_SKILL_LIMITS.fileBytes / 3) * 4).regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/),
+    executable: z.boolean().optional(),
+}).strict();
+export const skillFileBytes = (file) => file.data.length / 4 * 3 - (file.data.endsWith("==") ? 2 : file.data.endsWith("=") ? 1 : 0);
+export const platformSkillFilesSchema = z.array(platformSkillFileSchema).max(PLATFORM_TEAM_SKILL_LIMITS.files).superRefine((files, context) => {
+    const names = new Set();
+    let bytes = 0;
+    for (const [index, file] of files.entries()) {
+        const name = file.path.normalize("NFKC").toLowerCase(), size = skillFileBytes(file);
+        if (names.has(name) || files.some(other => other !== file && other.path.normalize("NFKC").toLowerCase().startsWith(`${name}/`)))
+            context.addIssue({ code: "custom", path: [index, "path"], message: "Skill file paths collide" });
+        names.add(name);
+        bytes += size;
+        if (size > PLATFORM_TEAM_SKILL_LIMITS.fileBytes)
+            context.addIssue({ code: "custom", path: [index, "data"], message: "Skill file is too large" });
+    }
+    if (bytes > PLATFORM_TEAM_SKILL_LIMITS.packageBytes)
+        context.addIssue({ code: "custom", message: "Skill package is too large" });
+});
+export function readSkillMarkdown(source) {
+    const text = source.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+    let content = text, frontmatter = "", name, description, hasMetadata = false;
+    if (text.startsWith("---\n")) {
+        const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(text);
+        if (!match)
+            throw new Error("The SKILL.md frontmatter has no closing ---.");
+        frontmatter = match[1];
+        content = text.slice(match[0].length);
+        if (frontmatter.length > 8192)
+            throw new Error("The SKILL.md frontmatter is too large.");
+        const document = parseDocument(frontmatter, { uniqueKeys: true });
+        if (document.errors.length)
+            throw new Error("The SKILL.md frontmatter is not valid YAML.");
+        const fields = z.object({ name: z.string().optional(), description: z.string().optional() }).passthrough().parse(document.toJS({ maxAliasCount: 50 }));
+        name = fields.name;
+        description = fields.description?.trim();
+        hasMetadata = Object.keys(fields).some(key => key !== "name" && key !== "description");
+    }
+    content = content.trim();
+    const heading = /^#\s+(.+?)\s*#*\s*(?:\n|$)/.exec(content);
+    if (heading)
+        content = content.slice(heading[0].length).trim();
+    return { name, description, title: heading?.[1], content, frontmatter, hasMetadata };
+}
+function validSkillFrontmatter(value) {
+    if (!value.trim())
+        return true;
+    try {
+        readSkillMarkdown(`---\n${value}\n---\n`);
+    }
+    catch {
+        return false;
+    }
+    let indirect = false;
+    visit(parseDocument(value), { Alias() { indirect = true; return visit.BREAK; },
+        Pair(_, pair) { if (isScalar(pair.key) && pair.key.value === "<<") {
+            indirect = true;
+            return visit.BREAK;
+        } } });
+    return !indirect;
+}
+function frontmatterObject(frontmatter) {
+    const document = parseDocument(frontmatter || "", { merge: true, uniqueKeys: true });
+    if (document.errors.length)
+        throw new Error("The SKILL.md frontmatter is not valid YAML.");
+    const value = document.toJS({ maxAliasCount: 50 });
+    if (value === null || value === undefined)
+        return {};
+    return z.record(z.string(), z.unknown()).parse(value);
+}
+export const SKILL_EXECUTING_FIELDS = ["hooks", "allowed-tools", "allowedTools", "mcpServers"];
+export const SKILL_EXECUTING_FILES = ["mcp.json"];
+export const skillExecutingFiles = (files) => (files ?? []).filter(file => SKILL_EXECUTING_FILES.includes(file.path.toLowerCase()));
+export function omitFrontmatterFields(frontmatter, fields) {
+    const value = frontmatterObject(frontmatter);
+    const removed = fields.filter(field => Object.hasOwn(value, field));
+    if (!removed.length)
+        return { frontmatter, removed };
+    for (const field of removed)
+        delete value[field];
+    return { frontmatter: Object.keys(value).length ? new Document(value).toString() : "", removed };
+}
+export function restoreFrontmatterFields(local, stored, fields) {
+    const target = parseDocument(local);
+    if (target.errors.length)
+        throw new Error("The SKILL.md frontmatter is not valid YAML.");
+    const source = frontmatterObject(stored), present = frontmatterObject(local);
+    const restored = fields.filter(field => Object.hasOwn(source, field) && !Object.hasOwn(present, field));
+    for (const field of restored)
+        target.set(field, source[field]);
+    return restored.length ? target.toString() : local;
+}
+export function frontmatterValue(frontmatter, field) {
+    const value = frontmatterObject(frontmatter);
+    return Object.hasOwn(value, field) ? value[field] : undefined;
+}
+export function renderSkillMarkdown(skill, name) {
+    const document = parseDocument(skill.frontmatter || "");
+    if (document.errors.length)
+        throw new Error("The SKILL.md frontmatter is not valid YAML.");
+    if (name)
+        document.set("name", name);
+    document.set("description", skill.description);
+    return `---\n${document.toString()}---\n# ${skill.title}\n\n${skill.content}\n`;
+}
+export const PLATFORM_TEAM_SKILL_KINDS = ["skill", "agent", "rule", "hook", "folder", "mcp_server", "permission"];
+export const platformTeamSkillKindSchema = z.enum(PLATFORM_TEAM_SKILL_KINDS);
+export const platformTeamSkillListKindSchema = z.enum([...PLATFORM_TEAM_SKILL_KINDS, "all"]);
+export const teamSkillKindHoldsFiles = (kind) => kind === "skill" || kind === "hook" || kind === "folder";
+export const teamSkillKindNeedsAdmin = (kind) => kind === "hook" || kind === "mcp_server" || kind === "permission";
+export const AGENT_EXECUTING_FIELDS = ["hooks", "mcpServers", "permissionMode"];
+export const teamItemExecutingFields = (kind) => kind === "skill" ? SKILL_EXECUTING_FIELDS : kind === "agent" ? AGENT_EXECUTING_FIELDS : [];
+export function teamItemNeedsAdmin(kind, definition) {
+    if (teamSkillKindNeedsAdmin(kind))
+        return true;
+    if (kind === "skill" && skillExecutingFiles(definition.files).length)
+        return true;
+    const fields = teamItemExecutingFields(kind), frontmatter = definition.frontmatter;
+    if (!fields.length || !frontmatter?.trim())
+        return false;
+    try {
+        return omitFrontmatterFields(frontmatter, fields).removed.length > 0;
+    }
+    catch {
+        return true;
+    }
+}
+export const TEAM_HOOK_DIR_PLACEHOLDER = "${RELVO_HOOK_DIR}";
+export const TEAM_AGENT_PLACEHOLDER = "${RELVO_AGENT}";
+function readJsonContent(content, key, what) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        throw new Error(`${what} is JSON.`);
+    }
+    const wrapped = z.object({ [key]: z.unknown() }).strict().safeParse(value);
+    return wrapped.success ? wrapped.data[key] : value;
+}
+const hookHandlerSchema = z.object({ type: z.string().min(1) }).passthrough();
+const hookGroupSchema = z.object({ matcher: z.string().optional(), hooks: z.array(hookHandlerSchema).min(1) }).passthrough();
+export const platformTeamHookConfigSchema = z.record(z.string().regex(/^[A-Z][A-Za-z]{1,40}$/, "Hook events are names such as PreToolUse"), z.array(hookGroupSchema).min(1));
+export function readTeamHookConfig(content) {
+    const what = "A hook's content is a JSON object of events, as under \"hooks\" in settings.json";
+    const parsed = platformTeamHookConfigSchema.safeParse(readJsonContent(content, "hooks", what));
+    if (!parsed.success)
+        throw new Error(`${what}: ${parsed.error.issues[0]?.message ?? "invalid"}.`);
+    return parsed.data;
+}
+const environmentName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,99}$/);
+export const platformTeamMcpServerSchema = z.union([
+    z.object({ type: z.literal("stdio").optional(), command: z.string().trim().min(1).max(500), args: z.array(z.string().max(2000)).max(100).optional(),
+        env: z.record(environmentName, z.string().max(2000)).optional() }).strict(),
+    z.object({ type: z.literal("http"), url: z.url({ protocol: /^https?$/ }).max(2000), headers: z.record(z.string().regex(/^[A-Za-z0-9-]{1,100}$/), z.string().max(2000)).optional(),
+        bearerTokenEnvVar: environmentName.optional() }).strict(),
+]);
+export function readTeamMcpServer(content) {
+    const what = "An MCP server's content is one server as in .mcp.json: {\"command\", \"args\", \"env\"} or {\"type\": \"http\", \"url\"}";
+    const parsed = platformTeamMcpServerSchema.safeParse(readJsonContent(content, "mcpServer", what));
+    if (!parsed.success)
+        throw new Error(`${what}: ${parsed.error.issues[0]?.message ?? "invalid"}.`);
+    return parsed.data;
+}
+const permissionRules = z.array(z.string().trim().min(1).max(500)).max(200).optional();
+export const platformTeamPermissionsSchema = z.object({ allow: permissionRules, ask: permissionRules, deny: permissionRules }).strict()
+    .refine(rules => Boolean(rules.allow?.length || rules.ask?.length || rules.deny?.length), "Name at least one rule");
+export function readTeamPermissions(content) {
+    const what = "Permission rules are JSON as under \"permissions\" in settings.json: {\"allow\", \"ask\", \"deny\"}";
+    const parsed = platformTeamPermissionsSchema.safeParse(readJsonContent(content, "permissions", what));
+    if (!parsed.success)
+        throw new Error(`${what}: ${parsed.error.issues[0]?.message ?? "invalid"}.`);
+    return parsed.data;
+}
+export const TEAM_HOOK_PLUGIN_HARNESSES = ["pi", "opencode", "amp"];
+export const TEAM_HOOK_NATIVE_FOLDER = "native";
+export function teamHookPluginHarnesses(files) {
+    const named = new Set();
+    for (const file of files ?? []) {
+        const [folder, harness, ...rest] = file.path.split("/");
+        if (folder !== TEAM_HOOK_NATIVE_FOLDER)
+            continue;
+        if (!rest.length || !TEAM_HOOK_PLUGIN_HARNESSES.some(name => name === harness))
+            return null;
+        named.add(harness);
+    }
+    return TEAM_HOOK_PLUGIN_HARNESSES.filter(name => named.has(name));
+}
+export function teamSkillKindIssues(kind, definition) {
+    const fields = [];
+    if (definition.files?.length && !teamSkillKindHoldsFiles(kind))
+        fields.push("files");
+    const reader = kind === "hook" ? readTeamHookConfig : kind === "mcp_server" ? readTeamMcpServer : kind === "permission" ? readTeamPermissions : undefined;
+    if (reader) {
+        try {
+            reader(definition.content);
+        }
+        catch {
+            fields.push("content");
+        }
+    }
+    if (kind === "hook") {
+        const plugins = teamHookPluginHarnesses(definition.files);
+        if (plugins === null)
+            fields.push("files");
+        else if (!plugins.length && !fields.includes("content") && !Object.keys(readTeamHookConfig(definition.content)).length)
+            fields.push("content");
+    }
+    return fields;
+}
+export const TEAM_HARNESSES = ["claude", "codex", "pi", "dsh", "opencode", "gemini", "kimi", "qwen", "cursor", "copilot", "amp", "droid"];
+export const teamHarnessSchema = z.enum(TEAM_HARNESSES);
+export const TEAM_HARNESS_NAMES = { claude: "Claude Code", codex: "Codex", pi: "Pi", dsh: "deepseek-harness", opencode: "OpenCode",
+    gemini: "Gemini CLI", kimi: "Kimi Code", qwen: "Qwen Code", cursor: "Cursor", copilot: "GitHub Copilot CLI", amp: "Amp", droid: "Factory Droid" };
+export const platformTeamHarnessesSchema = z.array(z.enum(["all", ...TEAM_HARNESSES])).max(TEAM_HARNESSES.length + 1)
+    .describe("The coding agents to write this item for when members sync: all (the default), or names such as claude, codex, gemini. On update, [] keeps the current choice.");
+export const storedTeamHarnesses = (requested) => requested.includes("all") ? []
+    : TEAM_HARNESSES.filter(harness => requested.includes(harness));
+export const teamItemTargets = (harnesses, harness) => !harnesses?.length || harnesses.includes(harness);
 export const PLATFORM_TEAM_SKILL_SLUG = /^[a-z][a-z0-9_]{1,39}$/;
 export const platformTeamSkillSlugSchema = z.string().regex(PLATFORM_TEAM_SKILL_SLUG).describe("Lowercase letters, digits and underscores, starting with a letter.");
 export const platformTeamSkillDefinitionSchema = z.object({
@@ -15,13 +248,22 @@ export const platformTeamSkillDefinitionSchema = z.object({
     description: z.string().trim().min(1).max(PLATFORM_TEAM_SKILL_LIMITS.descriptionChars).describe("When an agent should follow this skill; agents choose skills by it."),
     content: z.string().trim().min(1).refine(value => new TextEncoder().encode(value).byteLength <= PLATFORM_TEAM_SKILL_LIMITS.contentBytes, "The content is too long")
         .describe("Markdown: the steps, the tools to use (by name) and what to check. No secrets."),
+    files: platformSkillFilesSchema.optional(),
+    frontmatter: z.string().max(8192).refine(validSkillFrontmatter, "Invalid skill YAML metadata").optional(),
 }).strict();
-export const platformTeamSkillCreateSchema = platformTeamSkillDefinitionSchema.extend({ slug: platformTeamSkillSlugSchema }).strict();
-export const platformTeamSkillUpdateSchema = platformTeamSkillDefinitionSchema.extend({ expectedVersion: z.number().int().min(1) }).strict();
+export const platformTeamSkillCreateSchema = platformTeamSkillDefinitionSchema.extend({ slug: platformTeamSkillSlugSchema,
+    kind: platformTeamSkillKindSchema.optional().describe("skill (the default): steps an agent follows when a task fits; agent: a subagent's instructions, " +
+        "with description saying when to delegate to it; rule: instructions loaded in every session; folder: shared files, content saying what they are; " +
+        "hook, mcp_server, permission: JSON content, written only by team admins in the console. Only a skill, hook or folder holds files."),
+    harnesses: platformTeamHarnessesSchema.optional() }).strict();
+export const platformTeamSkillUpdateSchema = platformTeamSkillDefinitionSchema.extend({ expectedVersion: z.number().int().min(1), harnesses: platformTeamHarnessesSchema.optional() }).strict();
 export const platformTeamSkillRestoreSchema = z.object({ version: z.number().int().min(1), expectedVersion: z.number().int().min(1) }).strict();
-export const platformTeamSkillSchema = z.object({ slug: platformTeamSkillSlugSchema, title: z.string(), description: z.string(), content: z.string(),
+export const platformTeamSkillSchema = z.object({ slug: platformTeamSkillSlugSchema, kind: platformTeamSkillKindSchema.default("skill"),
+    adminOnly: z.boolean().default(false),
+    harnesses: z.array(teamHarnessSchema).default([]), title: z.string(), description: z.string(), content: z.string(),
+    files: platformSkillFilesSchema.optional(), frontmatter: z.string().optional(),
     version: z.number().int().min(1), createdAt: z.string(), updatedAt: z.string() });
-export const platformTeamSkillSummarySchema = platformTeamSkillSchema.omit({ content: true });
+export const platformTeamSkillSummarySchema = platformTeamSkillSchema.omit({ content: true, files: true, frontmatter: true });
 export const platformTeamSkillVersionSchema = z.object({ version: z.number().int().min(1), title: z.string(), createdAt: z.string() });
 export const platformSuggestionSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("custom_tool"), occurrences: z.number().int().min(2), lastSeenAt: z.string(),
@@ -31,13 +273,14 @@ export const platformSuggestionSchema = z.discriminatedUnion("kind", [
 ]);
 export const platformSuggestionsSchema = z.object({ suggestions: z.array(platformSuggestionSchema).max(20), since: z.string() });
 export const platformTeamSkillHistorySchema = platformTeamSkillVersionSchema.extend({ author: platformVersionAuthorSchema });
-export const platformTeamSkillVersionDetailSchema = platformTeamSkillSchema.pick({ title: true, description: true, content: true })
+export const platformTeamSkillVersionDetailSchema = platformTeamSkillSchema.pick({ title: true, description: true, content: true, files: true, frontmatter: true })
     .extend({ version: z.number().int().min(1), createdAt: z.string(), author: platformVersionAuthorSchema });
 const skillInput = projectScopeSchema.extend({ slug: platformTeamSkillSlugSchema });
 const skillResult = z.object({ skill: platformTeamSkillSchema }).strict();
 export const platformTeamSkillContracts = {
     listDeveloperTeamSkills: { input: projectScopeSchema.strict(), output: z.object({ skills: z.array(platformTeamSkillSummarySchema.extend({ canEdit: z.boolean(), canDelete: z.boolean() })),
-            canCreate: z.boolean() }).strict() },
+            canCreate: z.boolean(), canCreateAdminKinds: z.boolean().optional(),
+            storage: platformSkillStorageSchema.optional() }).strict() },
     getDeveloperTeamSkill: { input: skillInput.strict(), output: skillResult },
     createDeveloperTeamSkill: { input: projectScopeSchema.extend({ skill: platformTeamSkillCreateSchema }).strict(), output: skillResult },
     updateDeveloperTeamSkill: { input: skillInput.extend({ skill: platformTeamSkillUpdateSchema }).strict(), output: skillResult },