apps 0.0.1-beta.21 → 0.0.1-beta.22

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

@@ -38,15 +38,21 @@ export interface McpConnection {
     readonly timeoutMs: number;
 }
 export { ToolAnnotations as McpToolAnnotations } from "./tools.js";
-/** Native MCP result semantics. Protocol/transport failures use the Effect error channel. */
+/**
+ * Native MCP result semantics, and the value every MCP tool call returns. A tool's output
+ * schema is built from this declaration. Protocol/transport failures use the Effect error channel.
+ */
 export declare const McpToolResult: Schema.Struct<{
     readonly content: Schema.$Array<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
-    readonly structuredContent: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
-    readonly isError: Schema.optional<Schema.Boolean>;
-    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly structuredContent: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly isError: Schema.optionalKey<Schema.Boolean>;
+    readonly _meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type McpToolResult = typeof McpToolResult.Type;
-/** Remote metadata. Input/output schemas remain upstream JSON Schema documents. */
+/**
+ * Remote metadata. Input/output schemas remain upstream JSON Schema documents; the upstream
+ * output schema describes only a result's `structuredContent`.
+ */
 export declare const McpToolMetadata: Schema.Struct<{
     readonly name: Schema.String;
     readonly title: Schema.optional<Schema.String>;
@@ -83,10 +89,15 @@ export type McpServerHeader = typeof McpServerHeader.Type;
 export interface McpToolContext {
     readonly elicit?: Elicit;
 }
-/** A tool bound to one evaluation's account; do not reuse it with another account. */
-export interface McpTool extends McpToolMetadata {
+/**
+ * A tool bound to one evaluation's account; do not reuse it with another account. `output`
+ * decodes and describes the `McpToolResult` that `run` returns, with the upstream output schema
+ * under `structuredContent`.
+ */
+export interface McpTool extends Omit<McpToolMetadata, "outputSchema"> {
     readonly description: string;
     readonly input: Schema.Decoder<JsonValue>;
+    readonly output: Schema.Decoder<JsonValue>;
     readonly readOnly?: boolean;
     readonly run: (context: McpToolContext, input: JsonValue) => Effect.Effect<McpToolResult, McpError | ProviderError | ElicitationFailed>;
 }

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

@@ -17,8 +17,12 @@ 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>;

package/types/apps/src/implementation/mcp-call.d.ts

@@ -12,9 +12,9 @@ export declare const mcpCall: (client: Client, name: string, input: JsonObject,
     }[];
     readonly _meta?: {
         readonly [x: string]: Schema.Json;
-    } | undefined;
+    };
     readonly structuredContent?: {
         readonly [x: string]: Schema.Json;
-    } | undefined;
-    readonly isError?: boolean | undefined;
+    };
+    readonly isError?: boolean;
 }, ProviderError | ElicitationFailed | McpError, never>;

package/types/apps/src/implementation/mcp-client.d.ts

@@ -56,11 +56,11 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
         }[];
         readonly _meta?: {
             readonly [x: string]: Schema.Json;
-        } | undefined;
+        };
         readonly structuredContent?: {
             readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly isError?: boolean | undefined;
+        };
+        readonly isError?: boolean;
     }, ProviderError | import("../index.js").ElicitationFailed | McpError, never>;
 };
 /** Transport-independent operations consumed by the app tool adapter. */

package/types/apps/src/implementation/mcp.d.ts

@@ -46,11 +46,11 @@ export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.
         }[];
         readonly _meta?: {
             readonly [x: string]: Schema.Json;
-        } | undefined;
+        };
         readonly structuredContent?: {
             readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly isError?: boolean | undefined;
+        };
+        readonly isError?: boolean;
     }, ProviderError | import("../index.js").ElicitationFailed | McpError, never>;
 }, McpError, never>;
 /** Discover and compile all tools for connection probes and low-level consumers. */

package/types/apps/src/implementation/protocol-operations.d.ts

@@ -13,6 +13,9 @@ interface ProtocolOperation {
     readonly annotations?: ToolAnnotations | undefined;
     readonly _meta?: JsonObject | undefined;
     readonly input: Schema.Decoder<JsonValue>;
+    /** Checks and describes every returned value. */
+    readonly output?: Schema.Decoder<JsonValue> | undefined;
+    /** Describes the returned value without checking it; ignored when `output` is declared. */
     readonly outputSchema?: JsonObject | undefined;
     readonly run: (context: OperationContext, input: JsonValue) => Effect.Effect<unknown, unknown>;
 }

package/types/apps/src/implementation/schema.d.ts

@@ -120,6 +120,14 @@ export declare const compileJsonSchemaDecoder: (document: JsonObject) => Effect.
     };
 }, ValidationError, never>;
 export declare const lazyJsonSchemaDecoder: (document: () => JsonObject) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>, never, never>;
+/**
+ * A lazy decoder and the compilation it decodes with. Running `compile` first lets a caller
+ * reject an unsupported schema before a side effect whose result the decoder will check.
+ */
+export declare const preparedJsonSchemaDecoder: (document: JsonObject) => {
+    decoder: EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>;
+    compile: Effect.Effect<EffectSchema.Decoder<EffectSchema.Json, never>, ValidationError, never>;
+};
 /** Preserve the JSON document; compile its validator only when a value is first decoded. */
 export declare const jsonSchemaDecoder: (input: unknown) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>, ValidationError, never>;
 /** Import JSON metadata now; unsupported schemas and invalid values fail when parsed. */