apps 0.0.1-beta.54 → 0.0.1-beta.57

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

@@ -23,8 +23,8 @@ export * from "./events.js";
 export { AccountId, HttpUrl } from "./schema.js";
 export { OAuthClientAuth, OAuthSecretClientAuth, OAuthTokenRequestFormat, OAuthTokenResponse, } from "./provider.js";
 /**
- * The host protocol this framework speaks and its wire schemas. A later protocol replaces this
- * re-export; released protocol modules stay unchanged for host adapters.
+ * The host protocol this framework speaks and its wire schemas, from `protocols/current.ts`. The
+ * released protocol modules are frozen records that host adapters read.
  */
 export { frameworkProtocol } from "./protocol-version.js";
 export { protocol1 } from "./protocols/1.js";
@@ -33,20 +33,20 @@ export { protocol3 } from "./protocols/3.js";
 export { protocol4 } from "./protocols/4.js";
 export { protocol5 } from "./protocols/5.js";
 export { protocol6 } from "./protocols/6.js";
-export { protocol7, AccountCheckCommand, CredentialHost } from "./protocols/7.js";
+export { protocol7 } from "./protocols/7.js";
 export { protocol8 } from "./protocols/8.js";
 export { protocol9 } from "./protocols/9.js";
-export { protocol10, MigrateCommand, MigrateResult } from "./protocols/10.js";
-export { protocol11 } from "./protocols/11.js";
+export { protocol10 } from "./protocols/10.js";
+export { current as protocol11, AccountCheckCommand, CredentialHost, MigrateCommand, MigrateResult, } from "./protocols/current.js";
 export { AccountCheckResult, AccountInfo } from "./provider.js";
-import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostKindMismatch, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, McpError, SkillLoadFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/11.js";
-export { DeclaredRequirements, HostRequest } from "./protocols/11.js";
+import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostKindMismatch, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, McpError, SkillLoadFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/current.js";
+export { DeclaredRequirements, HostRequest } from "./protocols/current.js";
 /**
  * The MCP and skill loader failures as they cross the host boundary. Apps throw the author-facing
  * classes from `apps/mcp` and `apps/skills`.
  */
-export { McpError, SkillLoadFailed } from "./protocols/11.js";
-export { DeclaredAuthMethod, DeclaredProvider, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, HostRouterError, HostedRouter, HostedCatalog, HostedCatalogSummary, SkillSources, SkillCatalogResponse, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, HostKindMismatch, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/11.js";
+export { McpError, SkillLoadFailed } from "./protocols/current.js";
+export { DeclaredAuthMethod, DeclaredProvider, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, HostRouterError, HostedRouter, HostedCatalog, HostedCatalogSummary, SkillSources, SkillCatalogResponse, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, HostKindMismatch, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/current.js";
 /** Raw host inputs; the host boundary parses and redacts these immediately. */
 export type ResolvedAccountsInput = typeof ResolvedAccounts.Encoded;
 /** Trusted invocation context, supplied separately from the Request. */

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/11.ts` and notes/apps-publishing.md.
+ * snapshot. Its schemas are `protocols/current.ts`; released protocols are frozen. See notes/apps-publishing.md.
  * This file has no imports so the package build script can read it directly.
  */
 export declare const frameworkProtocol = 11;

package/types/apps/src/contracts/protocols/1.d.ts

@@ -3,15 +3,490 @@
  *
  * This protocol is released and frozen. Retained builds and published `apps` versions speak it,
  * and every later host must keep running and rebuilding them unchanged. `bun run check` compares
- * `protocol1` with `packages/apps/protocols/1.json` and fails on any difference, including changes
- * to the schemas it imports. Do not edit this file or the schemas it reaches to change the wire
- * format. Define the next protocol instead and give the host an adapter for this one. If a
- * referenced schema must change for other reasons, first copy its current definition here.
- * See notes/apps-publishing.md.
+ * `protocol1` with `packages/apps/protocols/1.json` and fails on any difference. The module imports
+ * only `effect` and the frozen OAuth sibling `./oauth.ts`, so no change elsewhere in the repository
+ * can alter it. Do not edit it to change the wire format: define the next protocol instead and
+ * give the host an adapter for this one. See notes/apps-publishing.md.
  */
 import { Schema } from "effect";
-import { OpenapiResponseError } from "../api-response-error.js";
-import { ElicitationFailed } from "../elicitation.js";
+import * as McpSchema from "effect/ai/McpSchema";
+/** JSON values carried by remote protocols such as MCP. */
+export declare const JsonValue: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+export type JsonValue = Schema.Json;
+/** A JSON object, distinct from an authored value schema. */
+export declare const JsonObject: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+export type JsonObject = typeof JsonObject.Type;
+/** Stable saved account identity supplied by a host, unchanged across refreshes. */
+export declare const AccountId: Schema.brand<Schema.String, "acc">;
+/** Parsed saved account identity. */
+export type AccountId = typeof AccountId.Type;
+declare const CacheError_base: Schema.Class<CacheError, Schema.TaggedStruct<"CacheError", {
+    readonly reason: Schema.Literals<readonly ["unavailable", "storage", "invalid", "capacity", "timeout"]>;
+}>, import("effect/Cause").YieldableError>;
+/** Expected cache failures never include keys, values or upstream exception text. */
+export declare class CacheError extends CacheError_base {
+}
+/** Stored values carry a version independent of their freshness clock. */
+export declare const CacheEntry: Schema.Struct<{
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly version: Schema.String;
+    readonly freshUntil: Schema.Finite;
+    readonly staleUntil: Schema.Finite;
+}>;
+/** Decoded cache value envelope. */
+export type CacheEntry = typeof CacheEntry.Type;
+/**
+ * Publication requires the lease acquired against the previously observed version.
+ * `acquire` reads one entry and claims its load in the same transaction, so a cache
+ * miss costs one round trip. `read` and `claim` remain for builds retained before it.
+ */
+export declare const CacheCommand: Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"read">;
+    readonly keys: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"acquire">;
+    readonly key: Schema.String;
+    /** Claim even a fresh entry, as an explicit refresh does. */
+    readonly refresh: Schema.Boolean;
+    /** Claim only while the entry still has this version. Absent accepts the current one. */
+    readonly version: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"claim">;
+    readonly key: Schema.String;
+    readonly version: Schema.NullOr<Schema.String>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"publish">;
+    readonly key: Schema.String;
+    readonly lease: Schema.String;
+    readonly entry: Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly version: Schema.String;
+        readonly freshUntil: Schema.Finite;
+        readonly staleUntil: Schema.Finite;
+    }>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"release">;
+    readonly key: Schema.String;
+    readonly lease: Schema.String;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"renew">;
+    readonly key: Schema.String;
+    readonly lease: Schema.String;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"write">;
+    readonly entries: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly entry: Schema.Struct<{
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly version: Schema.String;
+            readonly freshUntil: Schema.Finite;
+            readonly staleUntil: Schema.Finite;
+        }>;
+    }>>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"invalidate">;
+    readonly key: Schema.String;
+}>]>;
+/** Parsed host command; namespaces cannot be selected by app code. */
+export type CacheCommand = typeof CacheCommand.Type;
+/** Safe protocol envelope used at process boundaries. */
+export declare const CacheReply: Schema.Union<readonly [Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: typeof CacheError;
+}>]>;
+/** Names have Lakebed's identifier shape and are always bound SQL values, never raw SQL. */
+export declare const DataName: Schema.String;
+/** Stored fields and index terms use finite scalar values; absent optional fields are represented by null in transport. */
+export declare const Scalar: Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>;
+export type Scalar = typeof Scalar.Type;
+export declare const Field: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["string", "number", "boolean", "id", "userId"]>;
+    readonly optional: Schema.optional<Schema.Boolean>;
+    readonly default: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+    readonly references: Schema.optional<Schema.String>;
+}>;
+export type Field = typeof Field.Type;
+export declare const Index: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly fields: Schema.NonEmptyArray<Schema.String>;
+}>;
+export declare const Table: Schema.Struct<{
+    readonly fields: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["string", "number", "boolean", "id", "userId"]>;
+        readonly optional: Schema.optional<Schema.Boolean>;
+        readonly default: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+        readonly references: Schema.optional<Schema.String>;
+    }>>;
+    readonly indexes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly fields: Schema.NonEmptyArray<Schema.String>;
+    }>>;
+}>;
+export type Table = typeof Table.Type;
+export declare const DatabaseSchema: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly fields: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["string", "number", "boolean", "id", "userId"]>;
+        readonly optional: Schema.optional<Schema.Boolean>;
+        readonly default: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+        readonly references: Schema.optional<Schema.String>;
+    }>>;
+    readonly indexes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly fields: Schema.NonEmptyArray<Schema.String>;
+    }>>;
+}>>;
+export type DatabaseSchema = typeof DatabaseSchema.Type;
+/** Longest agent guidance an API error's recovery carries. */
+export declare const maxApiErrorInstructionsLength = 4096;
+/** Bounded recovery a declared API error published for its caller: a short next step and agent guidance. */
+export declare const ApiErrorRecovery: Schema.Struct<{
+    readonly action: Schema.NonEmptyString;
+    readonly instructions: Schema.NonEmptyString;
+}>;
+/** Recovery copied from an error response body; extra keys are dropped on decode. */
+export type ApiErrorRecovery = typeof ApiErrorRecovery.Type;
+/** Longest message an API error response carries. */
+export declare const maxApiErrorMessageLength = 4096;
+/** Bounded public fields from a response matching its declared API error schema. */
+export declare const ApiErrorResponse: Schema.Struct<{
+    readonly code: Schema.NonEmptyString;
+    readonly status: Schema.Int;
+    readonly message: Schema.NonEmptyString;
+    readonly recovery: Schema.optionalKey<Schema.Struct<{
+        readonly action: Schema.NonEmptyString;
+        readonly instructions: Schema.NonEmptyString;
+    }>>;
+}>;
+/** Safe projection of a response matching a declared API error schema. */
+export type ApiErrorResponse = typeof ApiErrorResponse.Type;
+declare const OpenapiResponseError_base: Schema.Class<OpenapiResponseError, Schema.TaggedStruct<"OpenapiResponseError", {
+    readonly code: Schema.NonEmptyString;
+    readonly status: Schema.Int;
+    readonly message: Schema.NonEmptyString;
+    readonly recovery: Schema.optionalKey<Schema.Struct<{
+        readonly action: Schema.NonEmptyString;
+        readonly instructions: Schema.NonEmptyString;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/** A validated OpenAPI failure with its declared message or static schema explanation. */
+export declare class OpenapiResponseError extends OpenapiResponseError_base {
+}
+/** Plain-data form request derived from the pinned MCP protocol schema. */
+export declare const FormElicitation: Schema.Struct<{
+    readonly mode: Schema.Literal<"form">;
+    readonly requestedSchema: Schema.toEncoded<Schema.Struct<{
+        readonly $schema: Schema.decodeTo<Schema.toType<Schema.optional<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+        readonly type: Schema.tag<"object">;
+        readonly properties: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [typeof McpSchema.LegacyTitledEnum, Schema.Union<readonly [typeof McpSchema.UntitledSingleSelectEnum, typeof McpSchema.TitledSingleSelectEnum]>, Schema.Union<readonly [typeof McpSchema.UntitledMultiSelectEnum, typeof McpSchema.TitledMultiSelectEnum]>]>, typeof McpSchema.ElicitationString, typeof McpSchema.ElicitationNumber, typeof McpSchema.ElicitationBoolean]>>;
+        readonly required: Schema.decodeTo<Schema.toType<Schema.optional<Schema.$Array<Schema.String>>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
+    }>>;
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly message: Schema.String;
+}>;
+export type FormElicitation = typeof FormElicitation.Type;
+/** MCP accept/decline/cancel response, without imposing a client or transport on app code. */
+export declare const ElicitationResponse: Schema.Union<readonly [Schema.Struct<{
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly action: Schema.Literal<"accept">;
+    readonly content: Schema.decodeTo<Schema.toType<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
+}>, Schema.Struct<{
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly action: Schema.Literals<readonly ["cancel", "decline"]>;
+}>]>;
+export type ElicitationResponse = typeof ElicitationResponse.Type;
+declare const ElicitationFailed_base: Schema.Class<ElicitationFailed, Schema.TaggedStruct<"ElicitationFailed", {
+    readonly reason: Schema.Literals<readonly ["unavailable", "transaction", "invalid-request", "invalid-response", "transport", "expired", "forbidden"]>;
+}>, import("effect/Cause").YieldableError>;
+/** A tool interaction could not be delivered or its request/response was invalid. No private payload is retained. */
+export declare class ElicitationFailed extends ElicitationFailed_base {
+}
+/** Safe reply for a runtime that crosses an RPC boundary. */
+export declare const ElicitationReply: Schema.Union<readonly [Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly response: Schema.Union<readonly [Schema.Struct<{
+        readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly action: Schema.Literal<"accept">;
+        readonly content: Schema.decodeTo<Schema.toType<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
+    }>, Schema.Struct<{
+        readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly action: Schema.Literals<readonly ["cancel", "decline"]>;
+    }>]>;
+}>, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: typeof ElicitationFailed;
+}>]>;
+export type ElicitationReply = typeof ElicitationReply.Type;
+/** Invocation consent requests no additional fields; arguments are reviewed, never edited in the form. */
+export declare const ApprovalElicitation: Schema.Struct<{
+    readonly requestedSchema: Schema.Struct<{
+        readonly type: Schema.Literal<"object">;
+        readonly properties: Schema.$Record<Schema.String, Schema.Never>;
+    }>;
+    readonly mode: Schema.Literal<"form">;
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly message: Schema.String;
+}>;
+export type ApprovalElicitation = typeof ApprovalElicitation.Type;
+/** Dispatch coalesces overdue ticks, so sub-minute intervals promise a cadence the runner cannot keep. */
+export declare const minimumIntervalMilliseconds = 60000;
+/** Calendar schedules use five cron fields and an explicit IANA time zone. */
+export declare const CalendarSchedule: Schema.Struct<{
+    readonly expression: Schema.NonEmptyString;
+    readonly timezone: Schema.NonEmptyString;
+}>;
+/** Validated timing crosses all runtime and persistence boundaries as data. */
+export declare const ScheduleTiming: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"interval">;
+    readonly milliseconds: Schema.Int;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"cron">;
+    readonly calendar: Schema.Struct<{
+        readonly expression: Schema.NonEmptyString;
+        readonly timezone: Schema.NonEmptyString;
+    }>;
+}>]>;
+export type ScheduleTiming = typeof ScheduleTiming.Type;
+/** A named trigger attached to the mutation it invokes, including schema-validated arguments. */
+export declare const OperationSchedule: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly timing: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"interval">;
+        readonly milliseconds: Schema.Int;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"cron">;
+        readonly calendar: Schema.Struct<{
+            readonly expression: Schema.NonEmptyString;
+            readonly timezone: Schema.NonEmptyString;
+        }>;
+    }>]>;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+export type OperationSchedule = typeof OperationSchedule.Type;
+/** Canonical resource path within one skill. */
+export declare const SkillFilePath: Schema.NonEmptyString;
+/** UTF-8 text resource. Reading a resource never executes it. */
+export declare const SkillFile: Schema.Struct<{
+    readonly path: Schema.NonEmptyString;
+    readonly content: Schema.String;
+}>;
+export type SkillFile = typeof SkillFile.Type;
+/** Agent Skills format constraints, not Executor execution or storage budgets. */
+export declare const skillFormatLimits: {
+    readonly nameCharacters: 64;
+    readonly descriptionCharacters: 1024;
+    readonly compatibilityCharacters: 500;
+};
+/** A lowercase alphanumeric skill directory name with single separating hyphens. */
+export declare const AppSkillName: Schema.NonEmptyString;
+/** Frontmatter is metadata only. In particular, allowed-tools never grants execution authority. */
+export declare const AppSkillMetadata: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.String;
+    readonly license: Schema.optionalKey<Schema.String>;
+    readonly compatibility: Schema.optionalKey<Schema.String>;
+    readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly "allowed-tools": Schema.optionalKey<Schema.String>;
+}>;
+export type AppSkillMetadata = typeof AppSkillMetadata.Type;
+/** Files use paths relative to this skill directory; reading one never executes its contents. */
+export declare const AppSkillSource: Schema.Struct<{
+    readonly files: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly content: Schema.String;
+    }>>;
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.String;
+    readonly license: Schema.optionalKey<Schema.String>;
+    readonly compatibility: Schema.optionalKey<Schema.String>;
+    readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly "allowed-tools": Schema.optionalKey<Schema.String>;
+}>;
+export type AppSkillSource = typeof AppSkillSource.Type;
+/** One evaluated catalog cannot contain ambiguous names. */
+export declare const AppSkills: Schema.$Array<Schema.Struct<{
+    readonly files: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly content: Schema.String;
+    }>>;
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.String;
+    readonly license: Schema.optionalKey<Schema.String>;
+    readonly compatibility: Schema.optionalKey<Schema.String>;
+    readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly "allowed-tools": Schema.optionalKey<Schema.String>;
+}>>;
+/** Advisory tool hints; neither the framework nor these declarations enforce access. */
+export declare const ToolAnnotations: Schema.Struct<{
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly readOnlyHint: Schema.optionalKey<Schema.Boolean>;
+    readonly destructiveHint: Schema.optionalKey<Schema.Boolean>;
+    readonly idempotentHint: Schema.optionalKey<Schema.Boolean>;
+    readonly openWorldHint: Schema.optionalKey<Schema.Boolean>;
+}>;
+export type ToolAnnotations = typeof ToolAnnotations.Type;
+/** Raw-byte ceiling shared by callback HTTP, app execution and the encoded host protocol. */
+export declare const WebhookTransportLimits: Schema.Struct<{
+    readonly maxBodyBytes: Schema.Int;
+}>;
+export type WebhookTransportLimits = typeof WebhookTransportLimits.Type;
+/** Requests and responses use the same existing transport bound. */
+export declare const defaultWebhookTransportLimits: {
+    readonly maxBodyBytes: number;
+};
+/** Bounded callback transport. Headers and base64 bytes preserve the provider signature input. */
+export declare const WebhookRequestData: Schema.Struct<{
+    readonly url: Schema.String;
+    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly body: Schema.String;
+}>;
+/** Each command runs with a fresh factory and the subscription's saved account selections. */
+export declare const WebhookCommand: Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"webhooks">;
+}>, Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-validate">;
+}>, Schema.Struct<{
+    readonly state: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-complete">;
+}>, Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-register">;
+}>, Schema.Struct<{
+    readonly state: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-unregister">;
+}>, Schema.Struct<{
+    readonly state: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly request: Schema.Struct<{
+        readonly url: Schema.String;
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+        readonly headers: Schema.$Record<Schema.String, Schema.String>;
+        readonly body: Schema.String;
+    }>;
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-handle">;
+}>]>;
+/** Parsed framework command; contains private host inputs and must not be logged. */
+export type WebhookCommand = typeof WebhookCommand.Type;
+/** Run identity is opaque and shared by author and SDK interfaces. */
+export declare const WorkflowRunId: Schema.brand<Schema.NonEmptyString, "wfr">;
+export type WorkflowRunId = typeof WorkflowRunId.Type;
+/** Stable names identify declarations and replay steps. */
+export declare const WorkflowName: Schema.NonEmptyString;
+/** Convert portable duration syntax to milliseconds; invalid or overflowing values are rejected. */
+export declare const workflowDurationMillis: (value: number | string) => number | undefined;
+/** Numbers are milliseconds; strings use a quantity and full unit, such as "5 minutes". */
+export declare const WorkflowDuration: Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>;
+export type WorkflowDuration = typeof WorkflowDuration.Type;
+/** Author retry and timeout options are passed to the durable engine. */
+export declare const WorkflowStepOptions: Schema.Struct<{
+    readonly retries: Schema.optionalKey<Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly delay: Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>;
+        readonly backoff: Schema.optionalKey<Schema.Literals<readonly ["constant", "linear", "exponential"]>>;
+    }>>;
+    readonly timeout: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>>;
+}>;
+export type WorkflowStepOptions = typeof WorkflowStepOptions.Type;
+/** Step outputs must fit the engine's persisted JSON result limit. */
+export declare const WorkflowValue: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+/** Private replay metadata is attached by the host, never accepted in author input. */
+export declare const WorkflowReplay: Schema.Struct<{
+    readonly key: Schema.NonEmptyString;
+    readonly fingerprint: Schema.NonEmptyString;
+}>;
+export type WorkflowReplay = typeof WorkflowReplay.Type;
+/** Portable discovery, input validation and execution commands. */
+export declare const WorkflowCommand: Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"workflows">;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"workflow-validate">;
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"workflow-run">;
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>]>;
+export type WorkflowCommand = typeof WorkflowCommand.Type;
+/** Private invocation RPC protocol shared by the host and isolated app bundle. */
+export declare const WorkflowRpcCommand: Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"do">;
+    readonly name: Schema.NonEmptyString;
+    readonly options: Schema.Struct<{
+        readonly retries: Schema.optionalKey<Schema.Struct<{
+            readonly limit: Schema.Int;
+            readonly delay: Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>;
+            readonly backoff: Schema.optionalKey<Schema.Literals<readonly ["constant", "linear", "exponential"]>>;
+        }>>;
+        readonly timeout: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>>;
+    }>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"sleep">;
+    readonly name: Schema.NonEmptyString;
+    readonly duration: Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"until">;
+    readonly name: Schema.NonEmptyString;
+    readonly timestamp: Schema.Finite;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"context">;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"invoke">;
+    readonly kind: Schema.Literals<readonly ["query", "mutation"]>;
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly stepId: Schema.NonEmptyString;
+    readonly timeout: Schema.Finite;
+}>]>;
+/** Serializable requests do not contain an app ID; authority is captured in the supplied capability. */
+export declare const WorkflowControlCommand: Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"start">;
+    readonly workflow: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly key: Schema.optionalKey<Schema.NonEmptyString>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"get">;
+    readonly run: Schema.brand<Schema.NonEmptyString, "wfr">;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"list">;
+    readonly workflow: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly cursor: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "wfr">>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"terminate">;
+    readonly run: Schema.brand<Schema.NonEmptyString, "wfr">;
+}>]>;
 declare const ProviderError_base: Schema.Class<ProviderError, Schema.TaggedStruct<"ProviderError", {
     readonly reason: Schema.Literals<readonly ["unauthorized", "forbidden", "rate_limited", "unavailable", "rejected"]>;
     readonly status: Schema.optional<Schema.Int>;
@@ -1634,7 +2109,7 @@ export declare const protocol1: {
             readonly requestedSchema: Schema.toEncoded<Schema.Struct<{
                 readonly $schema: Schema.decodeTo<Schema.toType<Schema.optional<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
                 readonly type: Schema.tag<"object">;
-                readonly properties: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [typeof import("effect/ai/McpSchema").LegacyTitledEnum, Schema.Union<readonly [typeof import("effect/ai/McpSchema").UntitledSingleSelectEnum, typeof import("effect/ai/McpSchema").TitledSingleSelectEnum]>, Schema.Union<readonly [typeof import("effect/ai/McpSchema").UntitledMultiSelectEnum, typeof import("effect/ai/McpSchema").TitledMultiSelectEnum]>]>, typeof import("effect/ai/McpSchema").ElicitationString, typeof import("effect/ai/McpSchema").ElicitationNumber, typeof import("effect/ai/McpSchema").ElicitationBoolean]>>;
+                readonly properties: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [typeof McpSchema.LegacyTitledEnum, Schema.Union<readonly [typeof McpSchema.UntitledSingleSelectEnum, typeof McpSchema.TitledSingleSelectEnum]>, Schema.Union<readonly [typeof McpSchema.UntitledMultiSelectEnum, typeof McpSchema.TitledMultiSelectEnum]>]>, typeof McpSchema.ElicitationString, typeof McpSchema.ElicitationNumber, typeof McpSchema.ElicitationBoolean]>>;
                 readonly required: Schema.decodeTo<Schema.toType<Schema.optional<Schema.$Array<Schema.String>>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
             }>>;
             readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
@@ -1713,7 +2188,9 @@ export declare const protocol1: {
         }>, Schema.Struct<{
             readonly operation: Schema.Literal<"acquire">;
             readonly key: Schema.String;
+            /** Claim even a fresh entry, as an explicit refresh does. */
             readonly refresh: Schema.Boolean;
+            /** Claim only while the entry still has this version. Absent accepts the current one. */
             readonly version: Schema.optionalKey<Schema.NullOr<Schema.String>>;
         }>, Schema.Struct<{
             readonly operation: Schema.Literal<"claim">;
@@ -1757,7 +2234,7 @@ export declare const protocol1: {
             readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
         }>, Schema.Struct<{
             readonly ok: Schema.Literal<false>;
-            readonly error: typeof import("../../../../app-cache/src/index.js").CacheError;
+            readonly error: typeof CacheError;
         }>]>;
     };
 };

package/types/apps/src/contracts/protocols/10.d.ts

@@ -1005,11 +1005,11 @@ export declare const protocol10: {
             readonly toolError: Schema.optionalKey<Schema.Literal<true>>;
         }>, Schema.Struct<{
             readonly ok: Schema.Literal<false>;
-            readonly error: Schema.Union<readonly [typeof import("../api-response-error.js").OpenapiResponseError, typeof import("../provider-error.js").ProviderError, typeof import("./9.js").McpError, typeof import("./9.js").SkillLoadFailed, typeof import("../workflows.js").WorkflowFailure, typeof import("./1.js").HostRequestInvalid, typeof import("./1.js").HostAccountsInvalid, typeof import("./8.js").HostDeclarationInvalid, typeof import("./8.js").HostEvaluationFailed, typeof import("./1.js").HostOperationNotFound, typeof import("./8.js").HostOperationFailed, typeof import("../../../../app-data/src/contracts/database.js").DatabaseLimitExceeded, typeof import("../../../../app-data/src/contracts/database.js").DatabaseFieldReserved, typeof import("./1.js").HostToolNotFound, typeof import("./1.js").HostInputInvalid, typeof import("./1.js").HostOutputInvalid, typeof import("./1.js").HostToolBlocked, typeof import("./1.js").HostToolApprovalRequired, typeof import("./1.js").HostToolPolicyFailed, typeof import("../elicitation.js").ElicitationFailed, typeof import("./4.js").HostKindMismatch]>;
+            readonly error: Schema.Union<readonly [typeof import("./1.js").OpenapiResponseError, typeof import("./8.js").ProviderError, typeof import("./9.js").McpError, typeof import("./9.js").SkillLoadFailed, typeof import("./3.js").WorkflowFailure, typeof import("./1.js").HostRequestInvalid, typeof import("./1.js").HostAccountsInvalid, typeof import("./8.js").HostDeclarationInvalid, typeof import("./8.js").HostEvaluationFailed, typeof import("./1.js").HostOperationNotFound, typeof import("./8.js").HostOperationFailed, typeof import("./3.js").DatabaseLimitExceeded, typeof import("./3.js").DatabaseFieldReserved, typeof import("./1.js").HostToolNotFound, typeof import("./1.js").HostInputInvalid, typeof import("./1.js").HostOutputInvalid, typeof import("./1.js").HostToolBlocked, typeof import("./1.js").HostToolApprovalRequired, typeof import("./1.js").HostToolPolicyFailed, typeof import("./1.js").ElicitationFailed, typeof import("./4.js").HostKindMismatch]>;
         }>]>;
         readonly catalog: Schema.Struct<{
             readonly routers: Schema.$Array<Schema.Struct<{
-                readonly error: Schema.optionalKey<Schema.Union<readonly [typeof import("../provider-error.js").ProviderError, typeof import("./9.js").McpError, typeof import("./9.js").SkillLoadFailed, typeof import("./8.js").HostDeclarationInvalid, typeof import("./8.js").HostEvaluationFailed]>>;
+                readonly error: Schema.optionalKey<Schema.Union<readonly [typeof import("./8.js").ProviderError, typeof import("./9.js").McpError, typeof import("./9.js").SkillLoadFailed, typeof import("./8.js").HostDeclarationInvalid, typeof import("./8.js").HostEvaluationFailed]>>;
                 readonly path: Schema.String;
                 readonly title: Schema.optionalKey<Schema.String>;
                 readonly description: Schema.optionalKey<Schema.String>;
@@ -1057,7 +1057,7 @@ export declare const protocol10: {
         }>;
         readonly catalogSummary: Schema.Struct<{
             readonly routers: Schema.$Array<Schema.Struct<{
-                readonly error: Schema.optionalKey<Schema.Union<readonly [typeof import("../provider-error.js").ProviderError, typeof import("./9.js").McpError, typeof import("./9.js").SkillLoadFailed, typeof import("./8.js").HostDeclarationInvalid, typeof import("./8.js").HostEvaluationFailed]>>;
+                readonly error: Schema.optionalKey<Schema.Union<readonly [typeof import("./8.js").ProviderError, typeof import("./9.js").McpError, typeof import("./9.js").SkillLoadFailed, typeof import("./8.js").HostDeclarationInvalid, typeof import("./8.js").HostEvaluationFailed]>>;
                 readonly path: Schema.String;
                 readonly title: Schema.optionalKey<Schema.String>;
                 readonly description: Schema.optionalKey<Schema.String>;
@@ -1339,7 +1339,7 @@ export declare const protocol10: {
             }>]>;
         }>, Schema.Struct<{
             readonly ok: Schema.Literal<false>;
-            readonly error: typeof import("../elicitation.js").ElicitationFailed;
+            readonly error: typeof import("./1.js").ElicitationFailed;
         }>]>;
         readonly workflowStep: Schema.Union<readonly [Schema.Struct<{
             readonly operation: Schema.Literal<"do">;
@@ -1375,7 +1375,7 @@ export declare const protocol10: {
             readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
         }>, Schema.Struct<{
             readonly ok: Schema.Literal<false>;
-            readonly error: typeof import("../workflows.js").WorkflowFailure;
+            readonly error: typeof import("./3.js").WorkflowFailure;
         }>]>;
         readonly workflowControl: Schema.Union<readonly [Schema.Struct<{
             readonly operation: Schema.Literal<"start">;
@@ -1444,7 +1444,7 @@ export declare const protocol10: {
             readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
         }>, Schema.Struct<{
             readonly ok: Schema.Literal<false>;
-            readonly error: typeof import("../../../../app-cache/src/index.js").CacheError;
+            readonly error: typeof import("./1.js").CacheError;
         }>]>;
     };
 };