apps 0.0.1-beta.3 → 0.0.1-beta.30

package/js/{chunk-FZJOYIZO.js → chunk-BTJMXW4I.js}

@@ -1,6 +1,6 @@
 import {
   Schema_exports
-} from "./chunk-FW5HBOIK.js";
+} from "./chunk-NXTXZ635.js";
 
 // src/contracts/storage.ts
 var StorageName = Schema_exports.NonEmptyString.check(Schema_exports.isMaxLength(200));

package/js/{chunk-HDTGZWP2.js → chunk-IMCEF6KE.js}

@@ -1,37 +1,52 @@
 import {
   adaptMcpTools,
+  answeredError,
   mcpClient,
   mcpJsonSchemaValidator
-} from "./chunk-RN2MXB4R.js";
+} from "./chunk-AE4FWJQU.js";
+import {
+  failOnNetworkRefusal
+} from "./chunk-PUC24GZP.js";
 import {
   accountProviderError,
-  httpProviderError
-} from "./chunk-ZJWDMTE3.js";
+  bodyUpstreamError,
+  httpProviderError,
+  providerErrorDetail
+} from "./chunk-KQCMHI3K.js";
 import {
+  McpCredentialsUnverified,
   McpError,
+  McpHealthInput,
   McpToolsOptions,
-  defaultMcpClientLimits
-} from "./chunk-MYYEW3RA.js";
+  NetworkRefused,
+  defaultMcpClientLimits,
+  mcpHealthReserveMs
+} from "./chunk-BSRU52RU.js";
 import {
   ProviderError
-} from "./chunk-W7D7WVSY.js";
+} from "./chunk-BRGF7VFN.js";
 import {
   captureTelemetry
-} from "./chunk-ZCAMUXSG.js";
+} from "./chunk-WGBI5MVX.js";
 import {
   FetchHttpClient_exports
-} from "./chunk-HDJH3RPR.js";
+} from "./chunk-BBTELEAN.js";
 import {
   HttpClientRequest_exports,
   HttpClient_exports
-} from "./chunk-QKHR7BMF.js";
+} from "./chunk-XGN5IFOZ.js";
 import {
+  Clock_exports,
   Deferred_exports,
   Effect_exports,
+  Match_exports,
+  Option_exports,
+  Predicate_exports,
   Redacted_exports,
+  Ref_exports,
   Schema_exports,
   Stream_exports
-} from "./chunk-FW5HBOIK.js";
+} from "./chunk-NXTXZ635.js";
 
 // src/implementation/mcp.ts
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
@@ -46,18 +61,45 @@ import {
   StreamableHTTPClientTransport,
   StreamableHTTPError
 } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+var unreadable = (error) => error instanceof SyntaxError || error instanceof Error && Predicate_exports.hasProperty(error, "issues") && Array.isArray(error.issues);
 var failure = (phase, error) => {
-  if (Schema_exports.is(ProviderError)(error) || Schema_exports.is(McpError)(error)) return error;
-  const status = error instanceof UnauthorizedError ? 401 : error instanceof StreamableHTTPError || error instanceof SseError ? error.code : void 0;
-  const provider = status === void 0 ? void 0 : httpProviderError(status);
-  if (provider !== void 0) return provider;
+  if (Schema_exports.is(ProviderError)(error) || Schema_exports.is(McpError)(error) || Schema_exports.is(NetworkRefused)(error))
+    return error;
+  const code = error instanceof UnauthorizedError ? 401 : error instanceof StreamableHTTPError || error instanceof SseError ? error.code : void 0;
+  if (code !== void 0 && code >= 300 && code <= 599)
+    return httpProviderError(code) ?? new McpError({ phase, reason: "request", status: code });
+  const upstream = answeredError(error);
   return new McpError({
     phase,
-    reason: error instanceof ProtocolError && error.code === ErrorCode.RequestTimeout ? "timeout" : "request",
-    ...status === void 0 ? {} : { status }
+    reason: code !== void 0 || unreadable(error) ? "invalid_response" : error instanceof ProtocolError && error.code === ErrorCode.RequestTimeout ? "timeout" : "request",
+    ...upstream === void 0 ? {} : { upstream }
   });
 };
-var transportFetch = (connection, telemetry, rejected) => (url, init) => Effect_exports.runPromiseWith(telemetry.context)(
+var errorBodyLimits = { maxBytes: 65536, readTimeoutMs: 2e3 };
+var errorBody = (response) => Effect_exports.gen(function* () {
+  const json = /^application\/(?:[\w.-]+\+)?json$/i.test(
+    response.headers["content-type"]?.split(";")[0]?.trim() ?? ""
+  );
+  const length = response.headers["content-length"];
+  if (!json || length !== void 0 && Number(length) > errorBodyLimits.maxBytes)
+    return { body: Stream_exports.toReadableStream(response.stream), upstream: void 0 };
+  const unreadable2 = new McpError({ phase: "transport", reason: "invalid_response" });
+  const read = yield* response.stream.pipe(
+    Stream_exports.mapError(() => unreadable2),
+    Stream_exports.limitBytes(errorBodyLimits.maxBytes, () => Stream_exports.fail(unreadable2)),
+    Stream_exports.decodeText,
+    Stream_exports.mkString,
+    Effect_exports.timeout(errorBodyLimits.readTimeoutMs),
+    Effect_exports.option
+  );
+  if (Option_exports.isNone(read)) return { body: null, upstream: void 0 };
+  const parsed = Schema_exports.decodeUnknownOption(Schema_exports.fromJsonString(Schema_exports.Json))(read.value);
+  return {
+    body: read.value,
+    upstream: Option_exports.isSome(parsed) ? bodyUpstreamError(parsed.value) : void 0
+  };
+});
+var transportFetch = (connection, telemetry, rejected, answered) => (url, init) => Effect_exports.runPromiseWith(telemetry.context)(
   Effect_exports.gen(function* () {
     const target = yield* Effect_exports.try({
       try: () => new URL(url),
@@ -67,26 +109,37 @@ var transportFetch = (connection, telemetry, rejected) => (url, init) => Effect_
       return yield* new McpError({ phase: "transport", reason: "invalid_input" });
     if (target.origin !== connection.url.origin || target.username || target.password)
       return yield* new McpError({ phase: "transport", reason: "invalid_response" });
-    const headers = new Headers(Redacted_exports.value(connection.headers));
-    new Headers(init?.headers).forEach((value, name) => headers.set(name, value));
     const request = yield* Effect_exports.try({
-      try: () => HttpClientRequest_exports.fromWeb(new Request(target, { ...init, headers })),
-      catch: () => failure("transport", void 0)
+      try: () => {
+        const headers = new Headers(Redacted_exports.value(connection.headers));
+        new Headers(init?.headers).forEach((value, name) => headers.set(name, value));
+        return HttpClientRequest_exports.fromWeb(new Request(target, { ...init, headers }));
+      },
+      // The provider's headers cannot form an HTTP request, such as a name with a space.
+      catch: () => new McpError({ phase: "transport", reason: "invalid_input" })
     });
     const client = yield* HttpClient_exports.HttpClient;
     const response = yield* client.execute(request);
+    yield* failOnNetworkRefusal(response).pipe(
+      Effect_exports.tapError((refused) => Deferred_exports.fail(rejected, refused))
+    );
+    if (response.status < 400)
+      return new Response(
+        [204, 205, 304].includes(response.status) ? null : Stream_exports.toReadableStream(response.stream),
+        {
+          status: response.status,
+          headers: response.headers
+        }
+      );
+    const { body, upstream } = yield* errorBody(response);
     const provider = httpProviderError(response.status, response.headers);
     if (provider !== void 0) {
-      yield* Deferred_exports.fail(rejected, provider);
-      return yield* provider;
+      const refused = providerErrorDetail(provider, { upstream });
+      yield* Deferred_exports.fail(rejected, refused);
+      return yield* refused;
     }
-    return new Response(
-      [204, 205, 304].includes(response.status) ? null : Stream_exports.toReadableStream(response.stream),
-      {
-        status: response.status,
-        headers: response.headers
-      }
-    );
+    yield* Ref_exports.set(answered, { status: response.status, upstream });
+    return new Response(body, { status: response.status, headers: response.headers });
   }).pipe(
     Effect_exports.provide(FetchHttpClient_exports.layer),
     Effect_exports.provideService(FetchHttpClient_exports.RequestInit, { redirect: "manual" }),
@@ -104,15 +157,30 @@ var transportFetch = (connection, telemetry, rejected) => (url, init) => Effect_
   ),
   init?.signal ? { signal: init.signal } : {}
 );
+var explain = (error, phase, response) => {
+  if (Schema_exports.is(ProviderError)(error)) return providerErrorDetail(error, { phase });
+  if (!Schema_exports.is(McpError)(error) || error.upstream !== void 0 || error.status === void 0 || response?.status !== error.status || response.upstream === void 0)
+    return error;
+  return new McpError({
+    phase: error.phase,
+    reason: error.reason,
+    status: error.status,
+    upstream: response.upstream
+  });
+};
+var explained = (phase, answered) => (error) => Ref_exports.get(answered).pipe(
+  Effect_exports.flatMap((response) => Effect_exports.fail(explain(error, phase, response)))
+);
 function withClient(connection, mode, use, changed) {
   const attempt = (kind) => Effect_exports.scoped(
     Effect_exports.gen(function* () {
       const telemetry = yield* captureTelemetry;
       const rejected = yield* Deferred_exports.make();
+      const answered = yield* Ref_exports.make(void 0);
       const pending = /* @__PURE__ */ new Set();
       const { client, transport } = yield* Effect_exports.acquireRelease(
         Effect_exports.sync(() => {
-          const fetch = transportFetch(connection, telemetry, rejected);
+          const fetch = transportFetch(connection, telemetry, rejected, answered);
           const client2 = new Client(
             { name: "executor-apps", version: "0.1.0" },
             {
@@ -168,10 +236,14 @@ function withClient(connection, mode, use, changed) {
         catch: (error) => failure("connect", error)
       }).pipe(
         Effect_exports.raceFirst(Deferred_exports.await(rejected)),
+        Effect_exports.catch(explained("connect", answered)),
         Effect_exports.timeout(connection.timeoutMs),
         Effect_exports.withSpan("provider.mcp.connect")
       );
-      return yield* use(client).pipe(Effect_exports.raceFirst(Deferred_exports.await(rejected)));
+      return yield* use(client).pipe(
+        Effect_exports.raceFirst(Deferred_exports.await(rejected)),
+        Effect_exports.catch(explained(mode, answered))
+      );
     })
   ).pipe(
     Effect_exports.withSpan("provider.mcp.session", {
@@ -216,9 +288,44 @@ var mcpClientEffect = (input, changed) => Effect_exports.gen(function* () {
     failure
   );
 });
+var refusesCredentials = (error) => Schema_exports.is(ProviderError)(error) && Match_exports.value(error.reason).pipe(
+  Match_exports.whenOr("unauthorized", "forbidden", "rejected", () => true),
+  Match_exports.whenOr("rate_limited", "unavailable", () => false),
+  Match_exports.exhaustive
+);
+var mcpHealthEffect = (check, options) => Effect_exports.gen(function* () {
+  const { deadline, timeoutMs, ...parsed } = yield* Schema_exports.decodeUnknownEffect(McpHealthInput)({
+    ...options,
+    accountId: check.account.id,
+    signal: check.signal,
+    deadline: check.deadline
+  }).pipe(Effect_exports.mapError(() => new McpError({ phase: "connect", reason: "invalid_input" })));
+  const end = Math.min(
+    (yield* Clock_exports.currentTimeMillis) + (timeoutMs ?? defaultMcpClientLimits.timeoutMs),
+    deadline === void 0 ? Number.POSITIVE_INFINITY : deadline - mcpHealthReserveMs
+  );
+  const remaining = Effect_exports.flatMap(
+    Clock_exports.currentTimeMillis,
+    (now) => end - now >= 1 ? Effect_exports.succeed(Math.floor(end - now)) : Effect_exports.fail(new McpError({ phase: "transport", reason: "timeout" }))
+  );
+  yield* (yield* mcpClientEffect({ ...parsed, timeoutMs: yield* remaining })).check;
+  return yield* remaining.pipe(
+    Effect_exports.flatMap(
+      (timeoutMs2) => mcpClientEffect({ url: parsed.url, signal: parsed.signal, timeoutMs: timeoutMs2 })
+    ),
+    Effect_exports.flatMap((anonymous) => anonymous.check),
+    Effect_exports.matchEffect({
+      onSuccess: () => Effect_exports.fail(new McpCredentialsUnverified({ anonymous: "answered" })),
+      // Executor's network refused the attempt, so the server never answered it.
+      onFailure: (error) => Schema_exports.is(NetworkRefused)(error) ? Effect_exports.fail(error) : refusesCredentials(error) ? Effect_exports.void : Effect_exports.fail(new McpCredentialsUnverified({ anonymous: error }))
+    }),
+    Effect_exports.withSpan("provider.mcp.anonymous")
+  );
+}).pipe(Effect_exports.withSpan("provider.mcp.health"));
 var mcpToolsEffect = (input) => mcpClientEffect(input).pipe(Effect_exports.flatMap(adaptMcpTools));
 
 export {
   mcpClientEffect,
+  mcpHealthEffect,
   mcpToolsEffect
 };

package/js/chunk-KQCMHI3K.js

@@ -0,0 +1,118 @@
+import {
+  ProviderError,
+  maxUpstreamMessageLength
+} from "./chunk-BRGF7VFN.js";
+import {
+  AccountId
+} from "./chunk-PWF2DRJ3.js";
+import {
+  Option_exports,
+  Schema_exports
+} from "./chunk-NXTXZ635.js";
+
+// src/implementation/upstream-error.ts
+var ErrorToken = Schema_exports.String.check(Schema_exports.isPattern(/^[A-Za-z0-9._-]{1,128}$/));
+var JsonRpcError = Schema_exports.Struct({
+  error: Schema_exports.Struct({ code: Schema_exports.Int, message: Schema_exports.String })
+});
+var OAuthError = Schema_exports.Struct({
+  error: ErrorToken,
+  error_description: Schema_exports.optional(Schema_exports.String)
+});
+var bounded = (message) => message.length <= maxUpstreamMessageLength ? message : `${message.slice(0, maxUpstreamMessageLength - 1)}\u2026`;
+var isShortenedUpstream = (message) => message.length === maxUpstreamMessageLength && message.endsWith("\u2026");
+var stated = (code, message) => ({
+  code,
+  ...message === void 0 || message === "" ? {} : { message: bounded(message) }
+});
+var bodyUpstreamError = (json) => {
+  const rpc = Schema_exports.decodeUnknownOption(JsonRpcError)(json);
+  if (Option_exports.isSome(rpc)) return stated(rpc.value.error.code, rpc.value.error.message);
+  const oauth = Schema_exports.decodeUnknownOption(OAuthError)(json);
+  if (Option_exports.isSome(oauth)) return stated(oauth.value.error, oauth.value.error_description);
+  return void 0;
+};
+var authParam = /([A-Za-z][A-Za-z0-9_-]*)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s,"]+))/g;
+var challengeUpstreamError = (header) => {
+  const bearer = header === void 0 ? -1 : header.search(/\bBearer\b/i);
+  if (header === void 0 || bearer === -1) return void 0;
+  const params = /* @__PURE__ */ new Map();
+  for (const [, name, quoted, token] of header.slice(bearer + "Bearer".length).matchAll(authParam))
+    if (name !== void 0 && !params.has(name.toLowerCase()))
+      params.set(name.toLowerCase(), quoted?.replace(/\\(.)/g, "$1") ?? token ?? "");
+  const code = Schema_exports.decodeUnknownOption(ErrorToken)(params.get("error"));
+  return Option_exports.isNone(code) ? void 0 : stated(code.value, params.get("error_description"));
+};
+
+// src/implementation/provider-error.ts
+var providerError = ({
+  reason,
+  status,
+  accountId,
+  phase,
+  upstream
+}) => new ProviderError({
+  reason,
+  ...status === void 0 ? {} : { status },
+  ...accountId === void 0 ? {} : { accountId },
+  ...phase === void 0 ? {} : { phase },
+  ...upstream === void 0 ? {} : { upstream }
+});
+function parseProviderError(error) {
+  return Schema_exports.decodeUnknownOption(ProviderError)(error).pipe(Option_exports.map(providerError));
+}
+function providerErrorDetail(error, detail) {
+  return providerError({
+    ...error,
+    phase: error.phase ?? detail.phase,
+    upstream: error.upstream ?? detail.upstream
+  });
+}
+function httpProviderError(status, headers = {}) {
+  const upstream = challengeUpstreamError(headers["www-authenticate"]);
+  if (status >= 500 && status <= 599)
+    return providerError({ reason: "unavailable", status, upstream });
+  if (status === 401) return providerError({ reason: "unauthorized", status, upstream });
+  if (status === 429) return providerError({ reason: "rate_limited", status, upstream });
+  if (status !== 403) return void 0;
+  const retry = headers["retry-after"];
+  if (headers["x-ratelimit-remaining"] === "0" || retry !== void 0 && (/^\d+$/.test(retry) || Number.isFinite(Date.parse(retry))))
+    return providerError({ reason: "rate_limited", status, upstream });
+  if (typeof upstream?.code === "string" && upstream.code.toLowerCase() === "insufficient_scope")
+    return providerError({ reason: "forbidden", status, upstream });
+  return providerError({ reason: "rejected", status, upstream });
+}
+function accountProviderError(error, accountId) {
+  const parsed = parseProviderError(error);
+  const account = Schema_exports.decodeUnknownOption(AccountId)(accountId);
+  if (Option_exports.isNone(parsed) || Option_exports.isNone(account)) return error;
+  return providerError({ ...parsed.value, accountId: account.value });
+}
+function graphqlProviderError(errors, status) {
+  const codes = errors.flatMap((error) => {
+    const parsed = Schema_exports.decodeUnknownOption(
+      Schema_exports.Struct({
+        type: Schema_exports.optional(Schema_exports.String),
+        extensions: Schema_exports.optional(Schema_exports.Struct({ code: Schema_exports.optional(Schema_exports.String) }))
+      })
+    )(error);
+    return Option_exports.isSome(parsed) ? [parsed.value.type, parsed.value.extensions?.code] : [];
+  });
+  if (codes.includes("RATE_LIMITED") || codes.includes("TOO_MANY_REQUESTS"))
+    return new ProviderError({ reason: "rate_limited", status });
+  if (codes.includes("UNAUTHENTICATED"))
+    return new ProviderError({ reason: "unauthorized", status });
+  if (codes.includes("FORBIDDEN")) return new ProviderError({ reason: "forbidden", status });
+  return void 0;
+}
+
+export {
+  isShortenedUpstream,
+  bodyUpstreamError,
+  providerError,
+  parseProviderError,
+  providerErrorDetail,
+  httpProviderError,
+  accountProviderError,
+  graphqlProviderError
+};

package/js/{chunk-BMOIAIVR.js → chunk-M2KEEOIQ.js}

@@ -1,6 +1,6 @@
 import {
   Schema_exports
-} from "./chunk-FW5HBOIK.js";
+} from "./chunk-NXTXZ635.js";
 
 // ../app-data/src/contracts/database.ts
 var DataName = Schema_exports.String.check(
@@ -113,6 +113,51 @@ var defaultDatabaseLimits = {
   valueBytes: 64 * 1024,
   indexBytes: 2048
 };
+var DatabaseLimit = Schema_exports.Literals([
+  "scanCalls",
+  "directGets",
+  "rowsRead",
+  "rowsReturned",
+  "pageSize",
+  "bytesRead",
+  "writes",
+  "valueBytes"
+]);
+var count = (value) => value.toLocaleString("en-US");
+var limitMessages = {
+  scanCalls: (maximum, requested) => `This invocation made ${count(requested)} index queries; the limit is ${count(maximum)}. Each first(), take(), collect(), count() or paginate() call on withIndex(...) counts once. Read related rows with one take() or paginate() over a shared index prefix instead of one first() per item, use get(id) for known IDs, or split the work across workflow steps.`,
+  directGets: (maximum, requested) => `This invocation made ${count(requested)} get(id) calls, including those made by update and delete; the limit is ${count(maximum)}. Split the work across workflow steps or mutations.`,
+  rowsRead: (maximum, requested) => `This invocation scanned ${count(requested)} rows; the limit is ${count(maximum)}. Narrow the index range, or page with paginate() across calls or workflow steps.`,
+  rowsReturned: (maximum, requested) => `This invocation returned ${count(requested)} rows; the limit is ${count(maximum)}. collect() fails rather than truncating. Page with paginate() across calls or workflow steps.`,
+  pageSize: (maximum, requested) => `One call asked for ${count(requested)} rows; take(n) and paginate({ numItems }) accept at most ${count(maximum)}. Page with paginate() across calls or workflow steps.`,
+  bytesRead: (maximum, requested) => `This invocation read ${count(requested)} bytes; the limit is ${count(maximum)}. Read fewer or smaller rows per call, or page with paginate() across calls or workflow steps.`,
+  writes: (maximum, requested) => `This mutation made ${count(requested)} writes; the limit is ${count(maximum)}. Split large ingests into batches, one batch per mutation or workflow step.`,
+  valueBytes: (maximum, requested) => `A row encodes to ${count(requested)} bytes; each row may use at most ${count(maximum)}. Store large content outside the row or split it across rows.`
+};
+var DatabaseLimitExceeded = class extends Schema_exports.TaggedError()(
+  "DatabaseLimitExceeded",
+  {
+    limit: DatabaseLimit,
+    maximum: Schema_exports.Int,
+    requested: Schema_exports.Int
+  }
+) {
+  get message() {
+    return limitMessages[this.limit](this.maximum, this.requested);
+  }
+};
+var reservedFieldNames = ["id", "createdAt", "updatedAt"];
+var DatabaseFieldReserved = class extends Schema_exports.TaggedError()(
+  "DatabaseFieldReserved",
+  {
+    table: Schema_exports.String,
+    field: Schema_exports.Literals(reservedFieldNames)
+  }
+) {
+  get message() {
+    return `Table "${this.table}" declares "${this.field}", which is reserved: the host adds id, createdAt and updatedAt to every row. Rename the field, or use the row's own ${this.field}.`;
+  }
+};
 var DatabaseRuntimeLimits = Schema_exports.Struct({
   maxCursorChars: Schema_exports.Int.check(Schema_exports.isGreaterThan(0)),
   connectionCacheCapacity: Schema_exports.Int.check(Schema_exports.isGreaterThan(0)),
@@ -134,5 +179,8 @@ export {
   AppDatabaseError,
   DatabaseLimits,
   defaultDatabaseLimits,
+  DatabaseLimitExceeded,
+  reservedFieldNames,
+  DatabaseFieldReserved,
   defaultDatabaseRuntimeLimits
 };

package/js/{chunk-YEJOQEII.js → chunk-MYCVMDWI.js}

@@ -1,6 +1,36 @@
 import {
+  SchemaGetter_exports,
   Schema_exports
-} from "./chunk-FW5HBOIK.js";
+} from "./chunk-NXTXZ635.js";
+
+// ../utils/src/api-error.ts
+var MessageField = Schema_exports.String.pipe(
+  Schema_exports.decodeTo(Schema_exports.optionalKey(Schema_exports.String), {
+    decode: SchemaGetter_exports.omit(),
+    encode: SchemaGetter_exports.passthrough()
+  })
+);
+function withFields(definition) {
+  const fields = definition.fields;
+  const message = definition.message;
+  const documentation = typeof message === "string" ? { description: message } : {};
+  const DefinedError = Schema_exports.Error(definition.tag)(
+    Schema_exports.TaggedStruct(definition.tag, { ...fields, message: MessageField }).annotate(
+      documentation
+    ),
+    { httpApiStatus: definition.status, ...documentation }
+  );
+  Object.defineProperty(DefinedError.prototype, "message", {
+    get() {
+      return typeof message === "string" ? message : message(this);
+    }
+  });
+  return DefinedError;
+}
+function define(definition) {
+  return "fields" in definition ? withFields(definition) : withFields({ ...definition, fields: {} });
+}
+var ApiError = { define };
 
 // src/contracts/skills.ts
 var SkillFilePath = Schema_exports.NonEmptyString.check(
@@ -45,9 +75,18 @@ var AppSkillSource = Schema_exports.Struct({
     )
   )
 });
-var SkillDefinitionInvalid = class extends Schema_exports.TaggedError()(
-  "SkillDefinitionInvalid",
-  {
+var skillDefinitionFailures = {
+  files: (file) => `The skill files of \u201C${file}\u201D are invalid: each needs a unique relative path, text content and a SKILL.md document.`,
+  directory: (file) => `\u201C${file}\u201D is not a valid skill directory. Skill directory names use lowercase letters and digits separated by single hyphens.`,
+  "missing-document": (file) => `\u201C${file}\u201D is missing.`,
+  frontmatter: (file) => `\u201C${file}\u201D must start with valid YAML frontmatter between --- lines.`,
+  metadata: (file) => `The frontmatter of \u201C${file}\u201D needs a valid name and description within the Agent Skills limits.`,
+  "name-mismatch": (file) => `The name in \u201C${file}\u201D does not match its skill directory.`
+};
+var SkillDefinitionInvalid = ApiError.define({
+  tag: "SkillDefinitionInvalid",
+  status: 400,
+  fields: {
     file: SkillFilePath,
     reason: Schema_exports.Literals([
       "files",
@@ -58,9 +97,8 @@ var SkillDefinitionInvalid = class extends Schema_exports.TaggedError()(
       "name-mismatch"
     ])
   },
-  { httpApiStatus: 400 }
-) {
-};
+  message: ({ file, reason }) => skillDefinitionFailures[reason](file)
+});
 var AppSkills = Schema_exports.Array(AppSkillSource).check(
   Schema_exports.makeFilter((skills) => new Set(skills.map((skill) => skill.name)).size === skills.length)
 );