apps 0.0.1-beta.4 → 0.0.1-beta.41

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

@@ -0,0 +1,84 @@
+/**
+ * What app code sees when Executor's app network refuses a request, and the fetch options the
+ * app runtime accepts. A refusal is Executor's decision, not the service's: the request never
+ * left Executor. App code runs on workerd, Cloudflare's runtime, on every host.
+ */
+import { Schema } from "effect";
+/**
+ * Why Executor's app network refused a request.
+ * - `private_address`: the destination is a private, loopback or internal address, and this
+ *   instance lets apps reach only public addresses.
+ * - `credential_host`: the request carries a credential handle, and its provider does not allow
+ *   the destination host.
+ * - `credential_app`: the request carries a credential handle that is not valid for this app.
+ * - `credential_expired`: the request carries an expired credential handle.
+ */
+export declare const NetworkRefusal: Schema.Union<readonly [Schema.Struct<{
+    readonly reason: Schema.Literal<"private_address">;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_host">;
+    /** The provider of the credential handle the request carried. */
+    readonly provider: Schema.String;
+    /** The hosts that provider's credentials may reach; empty when it declares none. */
+    readonly allowedHosts: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_app">;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_expired">;
+    /** The provider of the expired credential handle. */
+    readonly provider: Schema.String;
+}>]>;
+export type NetworkRefusal = typeof NetworkRefusal.Type;
+declare const NetworkRefused_base: Schema.Class<NetworkRefused, Schema.TaggedStruct<"NetworkRefused", {
+    /** The refused destination, with its port when the URL names one. */
+    readonly host: Schema.String;
+    readonly refusal: Schema.Union<readonly [Schema.Struct<{
+        readonly reason: Schema.Literal<"private_address">;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_host">;
+        /** The provider of the credential handle the request carried. */
+        readonly provider: Schema.String;
+        /** The hosts that provider's credentials may reach; empty when it declares none. */
+        readonly allowedHosts: Schema.$Array<Schema.String>;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_app">;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_expired">;
+        /** The provider of the expired credential handle. */
+        readonly provider: Schema.String;
+    }>]>;
+}>, import("effect/Cause").YieldableError>;
+/** Executor's app network refused a request before it reached the service. */
+export declare class NetworkRefused extends NetworkRefused_base {
+    get message(): string;
+}
+/**
+ * A refusal reaches app code as a response with this status and header. The header holds the
+ * encoded `NetworkRefused`, so it survives responses without a body, such as to `HEAD`; the
+ * body repeats it as JSON with its message. `ctx.fetch` and the framework's protocol helpers
+ * raise it as `NetworkRefused`; the platform's global `fetch` returns the response. Only
+ * Executor's app network sets the mark: it removes the header from a service's 421 response.
+ */
+export declare const networkRefusalStatus = 421;
+export declare const networkRefusalHeader = "x-executor-refused";
+/** The header's value: the refusal as JSON, URI-encoded so any provider name fits in a header. */
+export declare const NetworkRefusedHeader: Schema.compose<Schema.fromJsonString<typeof NetworkRefused>, Schema.StringFromUriComponent>;
+/** The response Executor's app network returns in place of a request it refused. */
+export declare const networkRefusalResponse: (refused: NetworkRefused) => Response;
+/** RequestInit options the app runtime restricts. */
+export declare const RestrictedFetchOption: Schema.Literals<readonly ["redirect", "cache", "integrity"]>;
+export type RestrictedFetchOption = typeof RestrictedFetchOption.Type;
+/** The values the app runtime accepts for each restricted option. */
+export declare const supportedFetchOptions: Readonly<Record<RestrictedFetchOption, ReadonlyArray<string>>>;
+declare const FetchOptionUnsupported_base: Schema.Class<FetchOptionUnsupported, Schema.TaggedStruct<"FetchOptionUnsupported", {
+    readonly option: Schema.Literals<readonly ["redirect", "cache", "integrity"]>;
+    readonly value: Schema.String;
+    readonly supported: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** `ctx.fetch` was given a standard RequestInit value the app runtime does not implement. */
+export declare class FetchOptionUnsupported extends FetchOptionUnsupported_base {
+    get message(): string;
+    /** What to do instead, when the standard value has an equivalent the runtime supports. */
+    private get advice();
+}
+export {};

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

@@ -1,11 +1,40 @@
 /** 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"]>;
+/** Which part of an OpenAPI document could not be compiled into tools. */
+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", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+/** A declared operation the importer left out, and why. */
+export declare const OpenapiSkippedOperation: Schema.Struct<{
+    /** The tool name the operation would have; reading that tool reports why it is missing. */
+    readonly name: Schema.String;
+    /** The HTTP method, such as `GET`. */
+    readonly method: Schema.String;
+    /** The path as the definition declares it. */
+    readonly path: Schema.String;
+    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", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+    readonly reason: Schema.String;
+}>;
+export type OpenapiSkippedOperation = typeof OpenapiSkippedOperation.Type;
 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 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", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
     readonly reason: Schema.String;
+    readonly skipped: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        /** The tool name the operation would have; reading that tool reports why it is missing. */
+        readonly name: Schema.String;
+        /** The HTTP method, such as `GET`. */
+        readonly method: Schema.String;
+        /** The path as the definition declares it. */
+        readonly path: Schema.String;
+        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", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+        readonly reason: Schema.String;
+    }>>>;
+    readonly origins: Schema.optionalKey<Schema.$Array<Schema.String>>;
 }>, import("effect/Cause").YieldableError>;
-/** A safe generation failure, translated into product HTTP errors at the boundary. */
+/**
+ * A safe generation failure. `reason` explains the cause; `skipped` lists the declared operations
+ * it left out and why, and `origins` the origins operations resolve to when none of them matches
+ * the allowed origin. Reading one left-out tool fails with this error for that operation alone.
+ */
 export declare class OpenapiCompileError extends OpenapiCompileError_base {
+    get message(): string;
 }
 export {};

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** Credential-free OpenAPI request declarations and validation schemas retained with app source. */
 import { Schema, type Effect } from "effect";
 import { JsonObject } from "./schema.js";
@@ -20,7 +21,8 @@ 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", "cookie"]>;
+    /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+    readonly in: Schema.Literals<readonly ["path", "query", "querystring", "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>;
@@ -45,7 +47,7 @@ export declare const OpenapiOperation: Schema.Struct<{
     /** 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 method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
     readonly path: Schema.String;
     readonly baseUrl: Schema.String;
     readonly openapi: Schema.String;
@@ -54,7 +56,8 @@ export declare const OpenapiOperation: Schema.Struct<{
     readonly request: Schema.Struct<{
         readonly parameters: Schema.$Array<Schema.Struct<{
             readonly name: Schema.String;
-            readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+            /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+            readonly in: Schema.Literals<readonly ["path", "query", "querystring", "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>;
@@ -75,6 +78,8 @@ export declare const OpenapiOperation: Schema.Struct<{
     }>;
     /** Streams remain in the metadata but cannot run through a single-result tool call. */
     readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
+    /** The operation's OpenAPI tags, shown to agents as labels within its router. */
+    readonly tags: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
     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<{
@@ -90,6 +95,8 @@ export declare const OpenapiOperation: Schema.Struct<{
     }>>>;
 }>;
 export type OpenapiOperation = typeof OpenapiOperation.Type;
+/** Safe methods, whose operations are queries unless `kinds` says otherwise. QUERY is OpenAPI 3.2's. */
+export declare const isOpenapiReadMethod: (method: OpenapiOperation["method"]) => method is "HEAD" | "GET" | "OPTIONS" | "QUERY";
 /** Map a selected account field to one Swagger credential value. */
 export declare const CredentialBinding: Schema.Struct<{
     readonly scheme: Schema.String;
@@ -123,7 +130,7 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         /** 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 method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
         readonly path: Schema.String;
         readonly baseUrl: Schema.String;
         readonly openapi: Schema.String;
@@ -132,7 +139,8 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly parameters: Schema.$Array<Schema.Struct<{
                 readonly name: Schema.String;
-                readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+                /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+                readonly in: Schema.Literals<readonly ["path", "query", "querystring", "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>;
@@ -153,6 +161,8 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         }>;
         /** Streams remain in the metadata but cannot run through a single-result tool call. */
         readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
+        /** The operation's OpenAPI tags, shown to agents as labels within its router. */
+        readonly tags: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
         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<{
@@ -197,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. */
@@ -210,7 +241,7 @@ 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 | OpenapiResponseError | ProviderError>;
+    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError | OpenapiResponseError | ProviderError | NetworkRefused>;
 }
 /** Executable operations keyed by their generated names. */
 export type OpenapiTools = Readonly<Record<string, OpenapiTool>>;
@@ -219,7 +250,12 @@ 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. */
+/**
+ * A sequence of JSON values, one per line or record: NDJSON, JSON Lines and `json-seq`, whose
+ * items OpenAPI 3.2 describes with `itemSchema`. The body is not one JSON value.
+ */
+export declare const isOpenapiJsonSequence: (type: string) => boolean;
+/** Media returned as text rather than a base64 file. JSON sequences remain unparsed text. */
 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. */
@@ -227,5 +263,5 @@ export declare const isOpenapiFileSchema: (shape: Readonly<Record<string, unknow
 /** 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 declare const openapiMediaKind: (type: string) => "form" | "json" | "binary" | "multipart" | "text";
 export {};

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

@@ -1,13 +1,13 @@
-/** Native operation declarations. Database access is an optional invocation capability. */
+/** Native operation declarations. SQL access is an optional invocation capability. */
 import type { Effect, Schema } from "effect";
 import type { Approval } from "./approval.js";
 import type { BoundContext, AccountSlots } from "./app.js";
-import type { Database, DatabaseReader, Tables } from "./storage.js";
+import type { Sql, SqlReader } from "./sql.js";
 import type { ToolAnnotations } from "./tools.js";
 import type { JsonObject } from "./schema.js";
 /** Host-bound operation capabilities; the author declaration refines accounts and storage. */
 export type OperationContext = BoundContext<AccountSlots> & {
-    readonly db?: DatabaseReader<Tables> | Database<Tables>;
+    readonly sql?: SqlReader | Sql;
 };
 /** The host validates input, checks approval, then owns the transaction and output validation. */
 export interface AppOperation<Input = unknown, Output = unknown> {
@@ -17,14 +17,13 @@ export interface AppOperation<Input = unknown, Output = unknown> {
     readonly annotations?: ToolAnnotations;
     readonly _meta?: JsonObject;
     readonly input: Schema.Decoder<Input>;
+    /** Checks every value `run` returns and is the output schema the operation is described with. */
     readonly output?: Schema.Decoder<Output>;
-    /** Upstream protocol result metadata; the protocol adapter validates its own result envelope. */
+    /**
+     * An upstream protocol's description of the value `run` returns, used only when `output` is
+     * absent. The host does not check it, so declare `output` when the result can be checked.
+     */
     readonly outputSchema?: JsonObject;
     readonly approval?: Approval<Input>;
     readonly run: (context: OperationContext, input: Input) => Effect.Effect<Output, unknown>;
 }
-/** Agent tool names carry the operation kind; catalogs may reuse the same local name. */
-export declare const OperationToolPrefixes: {
-    readonly query: "queries.";
-    readonly mutate: "mutations.";
-};

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

@@ -1,6 +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.
+ * snapshot. Released protocols are frozen: see `protocols/10.ts` and notes/apps-publishing.md.
  * This file has no imports so the package build script can read it directly.
  */
-export declare const frameworkProtocol = 2;
+export declare const frameworkProtocol = 10;