apps 0.0.1-beta.28 → 0.0.1-beta.30

package/types/apps/src/contracts/openapi.d.ts

@@ -207,11 +207,32 @@ export type OpenapiToolsOptions = Omit<typeof OpenapiToolsOptions.Type, "operati
     readonly operations: unknown;
     readonly definitions?: unknown;
 };
+/** The operation a failed call addressed: its method and templated path, never parameter values. */
+export declare const OpenapiFailedOperation: Schema.Struct<{
+    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
+    readonly path: Schema.String;
+}>;
+export type OpenapiFailedOperation = typeof OpenapiFailedOperation.Type;
+/** A response media type without parameters, such as `text/html`. */
+export declare const OpenapiMediaType: Schema.String;
 declare const OpenapiError_base: Schema.Class<OpenapiError, Schema.TaggedStruct<"OpenapiError", {
     readonly reason: Schema.Literals<readonly ["invalid_definition", "invalid_input", "request"]>;
     readonly status: Schema.optional<Schema.Number>;
+    /** Absent only when the definition itself could not be read. */
+    readonly operation: Schema.optional<Schema.Struct<{
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
+        readonly path: Schema.String;
+    }>>;
+    readonly contentType: Schema.optional<Schema.String>;
+    /** The response's `content-length`, when it declared one. */
+    readonly bytes: Schema.optional<Schema.Int>;
 }>, import("effect/Cause").YieldableError>;
-/** Safe failures omit request headers, credentials and upstream bodies. */
+/**
+ * Safe failures omit request headers, credentials and upstream body text: the failure message is
+ * also recorded in traces. A `request` failure with a status names the response that no declared
+ * error matched, or the success response whose body could not be read, by its media type and
+ * declared length.
+ */
 export declare class OpenapiError extends OpenapiError_base {
 }
 /** An ordinary native tool bound to one selected account. */

package/types/apps/src/contracts/skills.d.ts

@@ -1,5 +1,6 @@
 /** Portable Agent Skills returned by an app factory or loaded from published files. */
 import { Schema } from "effect";
+import { ApiError } from "../../../utils/src/api-error.js";
 /** Canonical resource path within one skill. */
 export declare const SkillFilePath: Schema.NonEmptyString;
 /** UTF-8 text resource. Reading a resource never executes it. */
@@ -40,13 +41,25 @@ export declare const AppSkillSource: Schema.Struct<{
     readonly "allowed-tools": Schema.optionalKey<Schema.String>;
 }>;
 export type AppSkillSource = typeof AppSkillSource.Type;
-declare const SkillDefinitionInvalid_base: Schema.Class<SkillDefinitionInvalid, Schema.TaggedStruct<"SkillDefinitionInvalid", {
+/** Invalid selected skill files fail the load. Errors identify the file without disclosing its contents. */
+export declare const SkillDefinitionInvalid: Schema.Class<{
+    readonly file: string;
+    readonly reason: "metadata" | "files" | "directory" | "missing-document" | "frontmatter" | "name-mismatch";
+} & ApiError & {
+    readonly _tag: "SkillDefinitionInvalid";
+}, Omit<Schema.TaggedStruct<"SkillDefinitionInvalid", {
     readonly file: Schema.NonEmptyString;
     readonly reason: Schema.Literals<readonly ["files", "directory", "missing-document", "frontmatter", "metadata", "name-mismatch"]>;
-}>, import("effect/Cause").YieldableError>;
-/** Invalid selected skill files fail the load. Errors identify the file without disclosing its contents. */
-export declare class SkillDefinitionInvalid extends SkillDefinitionInvalid_base {
-}
+} & {
+    readonly message: typeof import("../../../utils/src/api-error.js").MessageField;
+}>, "~type.make.in"> & {
+    readonly "~type.make.in": {
+        readonly reason: "metadata" | "files" | "directory" | "missing-document" | "frontmatter" | "name-mismatch";
+        readonly file: string;
+        readonly _tag?: "SkillDefinitionInvalid";
+    };
+}, ApiError>;
+export type SkillDefinitionInvalid = typeof SkillDefinitionInvalid.Type;
 /** One evaluated catalog cannot contain ambiguous names. */
 export declare const AppSkills: Schema.$Array<Schema.Struct<{
     readonly files: Schema.$Array<Schema.Struct<{

package/types/apps/src/implementation/openapi-compile.d.ts

@@ -1,9 +1,16 @@
 /** Compile an OpenAPI document into tool declarations inside the app runtime, never a second execution engine. */
 import { Effect, Schema } from "effect";
 import { JsonObject } from "../contracts/schema.js";
+import { OpenapiErrorResponse } from "../contracts/openapi.js";
 import { OpenapiCompileError as TemplateError } from "../contracts/openapi-compile.js";
 import type { OpenApiImport } from "../contracts/openapi-document.js";
 import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/openapi-document.js";
+import { type OpenApiDocument } from "./openapi-document.js";
+/** Keep tagged errors, including response/component refs and anyOf alternatives.
+ * Public text comes from a declared string message or the schema's static description.
+ * `scripts/check-api-errors.ts` applies this to Executor's own API documents.
+ */
+export declare function errorResponses(document: OpenApiDocument, operation: JsonObject, at: string): OpenapiErrorResponse[];
 /** Compile a revision of a live OpenAPI source into tool declarations for the app runtime.
  * The document is consumed: compilation upgrades it in place instead of copying it. It must be a
  * tree, with no object reached twice, as parsed JSON is.

package/types/utils/src/api-error.d.ts

@@ -0,0 +1,48 @@
+import { Schema, type Cause } from "effect";
+import "effect/unstable/httpapi";
+/**
+ * Encode the class's `message` getter as a required wire string. Decoding validates the field,
+ * then omits it, so the class derives its own message from the parsed payload and a supplied
+ * value never replaces it.
+ */
+export declare const MessageField: Schema.decodeTo<Schema.optionalKey<Schema.String>, Schema.String, never, never>;
+/** An expected API error whose response states its cause in a `message` derived from its fields. */
+export interface ApiError extends Cause.YieldableError {
+    readonly _tag: string;
+}
+type Header<Tag extends string> = {
+    readonly tag: Tag;
+    readonly status: number;
+};
+type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Header<Tag> & {
+    readonly fields: Fields & {
+        readonly [Key in "_tag" | "message"]?: never;
+    };
+    /**
+     * The cause, stated for API and agent callers. It is also the error's `message`, which traces
+     * record, so it never includes credentials, upstream response text or submitted values.
+     */
+    readonly message: string | ((fields: Schema.Struct.Type<Fields>) => string);
+};
+type ErrorFields<Tag extends string, Fields extends Schema.Struct.Fields> = Omit<Schema.TaggedStruct<Tag, Fields & {
+    readonly message: typeof MessageField;
+}>, "~type.make.in"> & {
+    readonly "~type.make.in": Schema.TaggedStruct<Tag, Fields>["~type.make.in"];
+};
+type ErrorClass<Tag extends string, Fields extends Schema.Struct.Fields> = Schema.Class<Schema.Struct.Type<Fields> & ApiError & {
+    readonly _tag: Tag;
+}, ErrorFields<Tag, Fields>, ApiError>;
+/** Define an error with no payload and a fixed message. Its tag is its public error code. */
+declare function define<const Tag extends string>(definition: Header<Tag> & {
+    readonly message: string;
+}): ErrorClass<Tag, {}>;
+/** Define an error whose message can depend on its parsed fields. */
+declare function define<const Tag extends string, const Fields extends Schema.Struct.Fields>(definition: Definition<Tag, Fields>): ErrorClass<Tag, Fields>;
+/**
+ * Define the schema, constructor and API message of an expected error together. Errors that need
+ * a user-facing title and recovery use `UserFacingError`, which carries the same message field.
+ */
+export declare const ApiError: {
+    define: typeof define;
+};
+export {};

package/js/{chunk-B5YJQU45.js → chunk-XGN5IFOZ.js}

@@ -4358,6 +4358,8 @@ export {
   bodyFormData,
   HttpClientRequest_exports,
   fromWeb2 as fromWeb,
+  HttpServerResponse_exports,
+  HttpServerRequest_exports,
   HttpTraceContext_exports,
   HttpClient,
   transformResponse,
@@ -4368,8 +4370,6 @@ export {
   TracerPropagationEnabled,
   layerMergedContext,
   HttpClient_exports,
-  HttpServerResponse_exports,
-  HttpServerRequest_exports,
   prefixPath,
   fromLiteral
 };