apps 0.0.1-beta.0 → 0.0.1-beta.2

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

@@ -0,0 +1,11 @@
+/** Shared OpenAPI compilation diagnostics. */
+import { Schema } from "effect";
+export declare const OpenapiCompileErrorCode: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+declare const OpenapiCompileError_base: Schema.Class<OpenapiCompileError, Schema.TaggedStruct<"OpenapiCompileError", {
+    readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A safe generation failure, translated into product HTTP errors at the boundary. */
+export declare class OpenapiCompileError extends OpenapiCompileError_base {
+}
+export {};

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

@@ -0,0 +1,53 @@
+/** OpenAPI boundary parsing. Unsupported transport/auth features fail before deployment. */
+import { Schema } from "effect";
+/** Parsed OpenAPI 3 source; individual operation references are resolved separately. */
+export declare const Specification: Schema.Struct<{
+    readonly openapi: Schema.String;
+    readonly servers: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly variables: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>>>;
+    readonly paths: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly components: Schema.optionalKey<Schema.Struct<{
+        readonly schemas: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>>;
+        readonly securitySchemes: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>>;
+    }>>;
+    readonly security: Schema.optionalKey<Schema.$Array<Schema.$Record<Schema.String, Schema.$Array<Schema.String>>>>;
+}>;
+export type Specification = typeof Specification.Type;
+export { OpenapiParameter as Parameter, OpenapiRequestBody as RequestBody } from "./openapi.js";
+/** Operation transport details. We never interpolate upstream executable code. */
+export declare const Operation: Schema.Struct<{
+    readonly operationId: Schema.optionalKey<Schema.String>;
+    readonly responses: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>>;
+    readonly summary: Schema.optionalKey<Schema.String>;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly parameters: Schema.optionalKey<Schema.$Array<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>>;
+    readonly requestBody: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly security: Schema.optionalKey<Schema.$Array<Schema.$Record<Schema.String, Schema.$Array<Schema.String>>>>;
+    readonly servers: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly variables: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>>>;
+}>;
+export type Operation = typeof Operation.Type;
+import type { CredentialBinding } from "./openapi.js";
+export type { OpenapiOperation as GeneratedOperation, CredentialBinding } from "./openapi.js";
+/** A secrets method can satisfy an AND-set of OpenAPI security schemes. */
+export interface GeneratedSecrets {
+    readonly name: string;
+    readonly label: string;
+    readonly bindings: readonly CredentialBinding[];
+}
+/** Import hints after product catalog overrides have been applied. */
+export interface OpenApiImport {
+    readonly name: string;
+    readonly connectUrl?: string | undefined;
+    /** Prefer protected-resource discovery when the API supports dynamic OAuth client registration. */
+    readonly oauthDiscoveryUrl?: string | undefined;
+    readonly auth?: {
+        readonly kind: string;
+        readonly header?: string | undefined;
+    } | undefined;
+    readonly scopes?: readonly string[] | undefined;
+}

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

@@ -1,89 +1,201 @@
-/** Normalized OpenAPI metadata retained with app source; no compiler or protocol client is required. */
+import type { ProviderError } from "./provider-error.js";
+/** Credential-free OpenAPI request declarations and validation schemas retained with app source. */
 import { Schema, type Effect } from "effect";
 import { JsonObject } from "./schema.js";
-/** One parameter's HTTP placement and serialization. */
-export declare const RequestParameter: Schema.Struct<{
+import { type OpenapiResponseError } from "./api-response-error.js";
+/** Tagged error shapes retain an explicit source for their public message. */
+export declare const OpenapiErrorResponse: Schema.Struct<{
+    readonly code: Schema.NonEmptyString;
+    readonly status: Schema.Int;
+    readonly message: Schema.Union<readonly [Schema.Struct<{
+        readonly source: Schema.Literal<"body">;
+    }>, Schema.Struct<{
+        readonly source: Schema.Literal<"schema">;
+        readonly value: Schema.NonEmptyString;
+    }>]>;
+    readonly schema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/** A retained declaration used to validate an HTTP failure before exposing its code. */
+export type OpenapiErrorResponse = typeof OpenapiErrorResponse.Type;
+/** Resolved OpenAPI parameter shared by import validation and request construction. */
+export declare const OpenapiParameter: Schema.Struct<{
     readonly name: Schema.String;
-    readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
-    readonly style: Schema.String;
-    readonly explode: Schema.Boolean;
+    readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+    readonly required: Schema.optionalKey<Schema.Boolean>;
+    readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly style: Schema.optionalKey<Schema.String>;
+    readonly explode: Schema.optionalKey<Schema.Boolean>;
+    readonly allowReserved: Schema.optionalKey<Schema.Boolean>;
+    readonly allowEmptyValue: Schema.optionalKey<Schema.Boolean>;
+    readonly content: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+export type OpenapiParameter = typeof OpenapiParameter.Type;
+/** Preserve media schemas and Encoding Objects for Swagger request construction. */
+export declare const OpenapiRequestBody: Schema.Struct<{
+    readonly required: Schema.optionalKey<Schema.Boolean>;
+    readonly content: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly encoding: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>>;
 }>;
-export type RequestParameter = typeof RequestParameter.Type;
 /** Credential-free operation data emitted by the OpenAPI importer. */
 export declare const OpenapiOperation: Schema.Struct<{
+    /** The tool name after `queries.` or `mutations.`, grouped as `<group>.<leaf>`. */
     readonly name: Schema.NonEmptyString;
+    /** The document's operationId, when it declares one. `kinds` overrides are keyed by it. */
+    readonly operationId: Schema.optionalKey<Schema.String>;
     readonly description: Schema.String;
     readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
     readonly path: Schema.String;
     readonly baseUrl: Schema.String;
-    readonly parameters: Schema.$Array<Schema.Struct<{
-        readonly name: Schema.String;
-        readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
-        readonly style: Schema.String;
-        readonly explode: Schema.Boolean;
-    }>>;
-    readonly body: Schema.Literals<readonly ["json", "base64", "none"]>;
+    readonly openapi: Schema.String;
+    readonly securitySchemes: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    /** The resolved OpenAPI Operation Object; Executor schemas remain separate. */
+    readonly request: Schema.Struct<{
+        readonly parameters: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+            readonly required: Schema.optionalKey<Schema.Boolean>;
+            readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            readonly style: Schema.optionalKey<Schema.String>;
+            readonly explode: Schema.optionalKey<Schema.Boolean>;
+            readonly allowReserved: Schema.optionalKey<Schema.Boolean>;
+            readonly allowEmptyValue: Schema.optionalKey<Schema.Boolean>;
+            readonly content: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        }>>;
+        readonly requestBody: Schema.optionalKey<Schema.Struct<{
+            readonly required: Schema.optionalKey<Schema.Boolean>;
+            readonly content: Schema.$Record<Schema.String, Schema.Struct<{
+                readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                readonly encoding: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>>;
+        }>>;
+        readonly security: Schema.$Array<Schema.$Record<Schema.String, Schema.$Array<Schema.String>>>;
+        readonly responses: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>;
     /** Streams remain in the metadata but cannot run through a single-result tool call. */
     readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
-    readonly security: Schema.$Array<Schema.$Array<Schema.String>>;
     readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
     readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly errorResponses: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly code: Schema.NonEmptyString;
+        readonly status: Schema.Int;
+        readonly message: Schema.Union<readonly [Schema.Struct<{
+            readonly source: Schema.Literal<"body">;
+        }>, Schema.Struct<{
+            readonly source: Schema.Literal<"schema">;
+            readonly value: Schema.NonEmptyString;
+        }>]>;
+        readonly schema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>>>;
 }>;
 export type OpenapiOperation = typeof OpenapiOperation.Type;
-/** One field's placement, potentially combined with other fields in an authentication method. */
+/** Map a selected account field to one Swagger credential value. */
 export declare const CredentialBinding: Schema.Struct<{
     readonly scheme: Schema.String;
     readonly field: Schema.String;
-    readonly in: Schema.Literals<readonly ["header", "query"]>;
-    readonly name: Schema.String;
+    readonly part: Schema.Literals<readonly ["value", "username", "password"]>;
     readonly prefix: Schema.String;
 }>;
 export type CredentialBinding = typeof CredentialBinding.Type;
 /** Selected credentials stay in the server runtime, separate from operation metadata. */
 export declare const OpenapiAccount: Schema.Struct<{
+    readonly id: Schema.optional<Schema.brand<Schema.String, "acc">>;
     readonly method: Schema.String;
     readonly fields: Schema.$Record<Schema.String, Schema.Unknown>;
 }>;
 export type OpenapiAccount = typeof OpenapiAccount.Type;
+/**
+ * Parameter values bound by the selected account, grouped as in tool input. Callers may omit
+ * these parameters; an explicit value still takes precedence and the API still authorizes it.
+ */
+export declare const OpenapiParameterDefaults: Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly query: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+}>;
+export type OpenapiParameterDefaults = typeof OpenapiParameterDefaults.Type;
 /** Parsed options for one account's evaluation. */
 export declare const OpenapiToolsOptions: Schema.Struct<{
     readonly operations: Schema.$Array<Schema.Struct<{
+        /** The tool name after `queries.` or `mutations.`, grouped as `<group>.<leaf>`. */
         readonly name: Schema.NonEmptyString;
+        /** The document's operationId, when it declares one. `kinds` overrides are keyed by it. */
+        readonly operationId: Schema.optionalKey<Schema.String>;
         readonly description: Schema.String;
         readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
         readonly path: Schema.String;
         readonly baseUrl: Schema.String;
-        readonly parameters: Schema.$Array<Schema.Struct<{
-            readonly name: Schema.String;
-            readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
-            readonly style: Schema.String;
-            readonly explode: Schema.Boolean;
-        }>>;
-        readonly body: Schema.Literals<readonly ["json", "base64", "none"]>;
+        readonly openapi: Schema.String;
+        readonly securitySchemes: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        /** The resolved OpenAPI Operation Object; Executor schemas remain separate. */
+        readonly request: Schema.Struct<{
+            readonly parameters: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+                readonly required: Schema.optionalKey<Schema.Boolean>;
+                readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                readonly style: Schema.optionalKey<Schema.String>;
+                readonly explode: Schema.optionalKey<Schema.Boolean>;
+                readonly allowReserved: Schema.optionalKey<Schema.Boolean>;
+                readonly allowEmptyValue: Schema.optionalKey<Schema.Boolean>;
+                readonly content: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>>;
+            readonly requestBody: Schema.optionalKey<Schema.Struct<{
+                readonly required: Schema.optionalKey<Schema.Boolean>;
+                readonly content: Schema.$Record<Schema.String, Schema.Struct<{
+                    readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                    readonly encoding: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                }>>;
+            }>>;
+            readonly security: Schema.$Array<Schema.$Record<Schema.String, Schema.$Array<Schema.String>>>;
+            readonly responses: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        }>;
         /** Streams remain in the metadata but cannot run through a single-result tool call. */
         readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
-        readonly security: Schema.$Array<Schema.$Array<Schema.String>>;
         readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
         readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly errorResponses: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly code: Schema.NonEmptyString;
+            readonly status: Schema.Int;
+            readonly message: Schema.Union<readonly [Schema.Struct<{
+                readonly source: Schema.Literal<"body">;
+            }>, Schema.Struct<{
+                readonly source: Schema.Literal<"schema">;
+                readonly value: Schema.NonEmptyString;
+            }>]>;
+            readonly schema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>>>;
     }>>;
+    /**
+     * Component schemas stored once per app and referenced as `#/$defs/<name>`. Operations
+     * generated before shared definitions carry their own `$defs` and omit this.
+     */
+    readonly definitions: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>>;
     readonly methods: Schema.$Record<Schema.String, Schema.$Array<Schema.Struct<{
         readonly scheme: Schema.String;
         readonly field: Schema.String;
-        readonly in: Schema.Literals<readonly ["header", "query"]>;
-        readonly name: Schema.String;
+        readonly part: Schema.Literals<readonly ["value", "username", "password"]>;
         readonly prefix: Schema.String;
     }>>>;
     readonly oauth: Schema.$Array<Schema.String>;
     readonly account: Schema.optional<Schema.Struct<{
+        readonly id: Schema.optional<Schema.brand<Schema.String, "acc">>;
         readonly method: Schema.String;
         readonly fields: Schema.$Record<Schema.String, Schema.Unknown>;
     }>>;
+    readonly parameterDefaults: Schema.optional<Schema.Struct<{
+        readonly path: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+        readonly query: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+        readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    }>>;
     readonly signal: Schema.optional<Schema.instanceOf<AbortSignal, AbortSignal>>;
     readonly fetch: Schema.optional<Schema.declare<typeof fetch, typeof fetch>>;
 }>;
 /** JSON imports are decoded at the helper boundary, without assertions in app source. */
-export type OpenapiToolsOptions = Omit<typeof OpenapiToolsOptions.Type, "operations"> & {
+export type OpenapiToolsOptions = Omit<typeof OpenapiToolsOptions.Type, "operations" | "definitions"> & {
     readonly operations: unknown;
+    readonly definitions?: unknown;
 };
 declare const OpenapiError_base: Schema.Class<OpenapiError, Schema.TaggedStruct<"OpenapiError", {
     readonly reason: Schema.Literals<readonly ["invalid_definition", "invalid_input", "request"]>;
@@ -98,8 +210,22 @@ export interface OpenapiTool {
     readonly readOnly: boolean;
     readonly outputSchema?: JsonObject;
     readonly input: Schema.Decoder<Schema.Json>;
-    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError>;
+    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError | OpenapiResponseError | ProviderError>;
 }
 /** Executable operations keyed by their generated names. */
 export type OpenapiTools = Readonly<Record<string, OpenapiTool>>;
+/** Tool calls buffer one bounded result; live event streams require an authored subscription. */
+export declare const defaultOpenapiResponseLimits: {
+    readonly maxBodyBytes: 16777216;
+    readonly readTimeoutMs: 30000;
+};
+/** Media returned as text rather than a base64 file. NDJSON remains an unparsed text result. */
+export declare const isOpenapiTextMedia: (type: string) => boolean;
+/** A form field that carries raw file bytes: OpenAPI 3.1 `contentMediaType` without an
+ * encoding, or the `format: binary` string that 3.1 documents still commonly use. */
+export declare const isOpenapiFileSchema: (shape: Readonly<Record<string, unknown>>) => boolean;
+/** JSON-safe binary result, independent of the host's file storage. */
+export declare const openapiBinaryResultSchema: JsonObject;
+/** Classify request media for JSON-safe tool arguments; Swagger owns wire serialization. */
+export declare const openapiMediaKind: (type: string) => "form" | "text" | "binary" | "json" | "multipart";
 export {};

package/types/apps/src/contracts/protocol-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The host protocol this framework speaks. It is written into `runtime.json` and every host
+ * snapshot. Released protocols are frozen: see `protocols/1.ts` and notes/apps-publishing.md.
+ * This file has no imports so the package build script can read it directly.
+ */
+export declare const frameworkProtocol = 1;