apps 0.0.1-beta.3 → 0.0.1-beta.31

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 "GET" | "HEAD" | "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

@@ -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/8.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;
+export declare const frameworkProtocol = 8;