apps 0.0.1-beta.4 → 0.0.1-beta.6

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

@@ -0,0 +1,59 @@
+/** Routers group operations. Keys form tool paths; each operation keeps its own kind. */
+import { Schema, type Effect } from "effect";
+import type { HostedTool, HostedToolSummary } from "./host.js";
+import type { AppOperation } from "./operations.js";
+/** Object keys that JavaScript gives special meaning, so no router may use them. */
+export declare const reservedRouterKeys: ReadonlySet<string>;
+/** One static path segment. Dots separate segments, so a key never contains one. */
+export declare const RouterKey: Schema.String;
+/** An image a client may show beside a router, such as an MCP server's own icon. Models never read it. */
+export declare const RouterIcon: Schema.Struct<{
+    readonly src: Schema.NonEmptyString;
+    readonly mimeType: Schema.optionalKey<Schema.String>;
+    readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+}>;
+export type RouterIcon = typeof RouterIcon.Type;
+/**
+ * What an agent should know about a group of tools. `instructions` is published as a skill;
+ * `tags` describes labels that tools in this router carry, such as OpenAPI tags.
+ */
+export declare const RouterMeta: Schema.Struct<{
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly instructions: Schema.optionalKey<Schema.String>;
+    readonly icons: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly src: Schema.NonEmptyString;
+        readonly mimeType: Schema.optionalKey<Schema.String>;
+        readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+    }>>>;
+    readonly tags: Schema.optionalKey<Schema.$Record<Schema.NonEmptyString, Schema.String>>;
+}>;
+export type RouterMeta = typeof RouterMeta.Type;
+/** A statically declared router. Children are operations or further routers. */
+export interface AppRouter {
+    readonly kind: "router";
+    readonly meta?: RouterMeta;
+    readonly children: Readonly<Record<string, AppNode>>;
+}
+/**
+ * A router whose tools are discovered when read, such as an MCP server or OpenAPI document.
+ * Names are relative to the router and may contain dots. `readOnly: true` marks a query;
+ * anything else is a mutation. Resolution never requires listing.
+ */
+export interface DynamicRouter {
+    readonly kind: "dynamic";
+    /** Metadata supplied by the source. Author metadata on the router takes precedence. */
+    readonly meta?: () => Effect.Effect<RouterMeta, unknown>;
+    readonly list: () => Effect.Effect<readonly HostedTool[], unknown>;
+    readonly resolve: (name: string) => Effect.Effect<AppOperation | undefined, unknown>;
+    /** Names and descriptions without schemas. Omitted sources reduce list(). */
+    readonly summaries?: () => Effect.Effect<readonly HostedToolSummary[], unknown>;
+    /** One tool's full metadata without listing. Omitted sources search list(). */
+    readonly describe?: (name: string) => Effect.Effect<HostedTool | undefined, unknown>;
+    /** Static author metadata, merged over the source's metadata. */
+    readonly overrides?: RouterMeta;
+}
+/** Anything a router can contain. */
+export type AppNode = AppOperation | AppRouter | DynamicRouter;

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

@@ -2,7 +2,7 @@
 import { Schema, type Effect } from "effect";
 import type { RowMetadata, ReadTable, WriteTable } from "../../../app-data/src/index.js";
 import type { Fields, ObjectValue } from "../implementation/schema.js";
-import type { DatabaseSchema, DatabaseSession, AppDatabaseError } from "../../../app-data/src/contracts/database.js";
+import type { DatabaseSchema, DatabaseSession, DatabaseError } from "../../../app-data/src/contracts/database.js";
 /** Names for authored operations and tables. */
 export declare const StorageName: Schema.NonEmptyString;
 declare const AppStorageUnavailable_base: Schema.Class<AppStorageUnavailable, Schema.TaggedStruct<"AppStorageUnavailable", {}>, import("effect/Cause").YieldableError>;
@@ -15,8 +15,8 @@ export declare class AppStorageError extends AppStorageError_base {
 }
 /** The adapter owns the database connection and transaction for the whole authored invocation. */
 export interface AppStorage {
-    readonly read: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError | AppStorageUnavailable | AppStorageError>;
-    readonly mutate: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError | AppStorageUnavailable | AppStorageError>;
+    readonly read: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError | AppStorageUnavailable | AppStorageError>;
+    readonly mutate: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError | AppStorageUnavailable | AppStorageError>;
 }
 type InputValue<F extends Fields> = {
     readonly [K in keyof F as F[K]["optionalValue"] extends true ? never : F[K] extends {

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

@@ -24,14 +24,33 @@ export declare const WorkflowStepOptions: Schema.Struct<{
     readonly timeout: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>>;
 }>;
 export type WorkflowStepOptions = typeof WorkflowStepOptions.Type;
+/**
+ * Where and why a run failed: the failing step and the error the app's own code raised, its
+ * message bounded and with account secrets replaced. Runs from before these fields existed have none.
+ */
+export declare const WorkflowFailureDetail: {
+    step: Schema.optionalKey<Schema.String>;
+    errorName: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+};
+/** A failed run's recorded step and app error. */
+export declare const WorkflowRunFailure: Schema.Struct<{
+    step: Schema.optionalKey<Schema.String>;
+    errorName: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+}>;
+export type WorkflowRunFailure = typeof WorkflowRunFailure.Type;
 declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedStruct<"WorkflowFailure", {
     readonly reason: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
     readonly retryable: Schema.Boolean;
+    readonly step: Schema.optionalKey<Schema.String>;
+    readonly errorName: Schema.optionalKey<Schema.String>;
+    readonly message: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
-/** Safe failures cross host boundaries without authored exceptions or account fields. */
+/** Failures cross host boundaries as reason codes plus the app's own bounded error detail. */
 export declare class WorkflowFailure extends WorkflowFailure_base {
 }
-/** Explicitly stop retrying an authored step. Its message stays inside the app runtime. */
+/** Explicitly stop retrying an authored step. Its message is reported like any step error. */
 export declare class NonRetryableError extends Error {
     readonly name = "NonRetryableError";
 }
@@ -45,7 +64,7 @@ export declare const HostedWorkflow: Schema.Struct<{
     readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type HostedWorkflow = typeof HostedWorkflow.Type;
-/** Results are available only on completed runs; failure details are safe reason codes. */
+/** Results are available only on completed runs; failures carry a reason code and app error detail. */
 export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
     readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
     readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
@@ -66,6 +85,12 @@ export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
 }>, Schema.Struct<{
     readonly status: Schema.Literal<"errored">;
     readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+    /** The failing step and the app's own error, when the run recorded them. */
+    readonly failure: Schema.optionalKey<Schema.Struct<{
+        step: Schema.optionalKey<Schema.String>;
+        errorName: Schema.optionalKey<Schema.String>;
+        message: Schema.optionalKey<Schema.String>;
+    }>>;
     readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
@@ -104,6 +129,12 @@ export declare const WorkflowRunPage: Schema.Struct<{
     }>, Schema.Struct<{
         readonly status: Schema.Literal<"errored">;
         readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+        /** The failing step and the app's own error, when the run recorded them. */
+        readonly failure: Schema.optionalKey<Schema.Struct<{
+            step: Schema.optionalKey<Schema.String>;
+            errorName: Schema.optionalKey<Schema.String>;
+            message: Schema.optionalKey<Schema.String>;
+        }>>;
         readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;

package/types/apps/src/graphql.d.ts

@@ -4,7 +4,5 @@ import { type GraphqlCatalogOptions } from "./implementation/graphql-catalog.js"
 export { GraphqlError, type GraphqlToolsOptions } from "./contracts/graphql.js";
 export type { GraphqlCatalogOptions } from "./implementation/graphql-catalog.js";
 /** Lazy tools with optional persistent metadata caching for the selected account. */
-export declare const graphqlOperations: (options: GraphqlCatalogOptions, kinds?: OperationKinds) => Promise<{
-    dynamicTools: import("./contracts/dynamic-tools.js").DynamicTools;
-}>;
+export declare const graphqlRouter: (options: GraphqlCatalogOptions, kinds?: OperationKinds) => Promise<import("./index.js").RouterDeclaration<unknown, unknown>>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";

package/types/apps/src/implementation/account-router.d.ts

@@ -0,0 +1,12 @@
+import { type RouterDeclaration } from "./router.js";
+/**
+ * Discover each selected account's router and combine matching names.
+ * Calls take { accountId, input }; each branch retains its account's input schema,
+ * credentials, approval and output validation. Empty selections expose no operations.
+ * Discovery is sequential and cancellation follows the caller's signal.
+ */
+export declare const accountRouter: <Account extends {
+    readonly id: string;
+}>(accounts: readonly Account[], discover: (account: Account) => Promise<RouterDeclaration>, options: {
+    readonly signal: AbortSignal;
+}) => Promise<RouterDeclaration>;

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

@@ -4,7 +4,7 @@ import type { AppRequirements, AppContext, QueryContext, MutationContext, Webhoo
 import { type PromiseMethods } from "./authoring.js";
 import { type WorkflowDeclaration } from "./workflows.js";
 import type { WorkflowContext } from "../contracts/workflows.js";
-import { type OperationDeclaration } from "./operations.js";
+import { type RouterDeclaration } from "./router.js";
 import { type Schema } from "./schema.js";
 type PromiseCatalog<Catalog> = Catalog extends Readonly<Record<string, object>> ? {
     readonly [Name in keyof Catalog]: {
@@ -14,15 +14,16 @@ type PromiseCatalog<Catalog> = Catalog extends Readonly<Record<string, object>>
 /** Author definition projected from native capabilities. Excluding callable objects keeps
  * factories from being inferred as definitions and preserves contextual handler inference. */
 export type AppDefinition<Requirements extends AppRequirements> = {
-    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>>>> : Key extends "schedules" ? Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>>>> : Key extends "queries" ? Readonly<Record<string, OperationDeclaration<"query", QueryContext<Requirements>>>> : Key extends "mutations" ? Readonly<Record<string, OperationDeclaration<"mutation", MutationContext<Requirements>>>> : Key extends "webhooks" ? PromiseCatalog<NonNullable<NativeDefinition<WebhookContext<Requirements>>[Key]>> : NativeDefinition<WebhookContext<Requirements>>[Key];
+    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>>>> : Key extends "schedules" ? Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>>>> : Key extends "tools" ? RouterDeclaration<QueryContext<Requirements>, MutationContext<Requirements>> : Key extends "webhooks" ? PromiseCatalog<NonNullable<NativeDefinition<WebhookContext<Requirements>>[Key]>> : NativeDefinition<WebhookContext<Requirements>>[Key];
 } & {
     readonly name?: never;
-    readonly tools?: never;
+    readonly queries?: never;
+    readonly mutations?: never;
     readonly call?: never;
 };
 /** Adapt operation and webhook catalogs without evaluating their handlers. */
 export type EffectDefinition<Def> = {
-    readonly [Key in keyof Def]: Key extends "dynamicTools" ? NonNullable<NativeDefinition<unknown>["dynamicTools"]> : Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "queries" | "mutations" ? Readonly<Record<string, import("../contracts/operations.js").AppOperation>> : Key extends "webhooks" ? NonNullable<NativeDefinition<WebhookContext>["webhooks"]> : Key extends "skills" ? NonNullable<NativeDefinition<unknown>["skills"]> : Key extends "dynamicSkills" ? NonNullable<NativeDefinition<unknown>["dynamicSkills"]> : Def[Key];
+    readonly [Key in keyof Def]: Key extends "tools" ? NonNullable<NativeDefinition<unknown>["tools"]> : Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "webhooks" ? NonNullable<NativeDefinition<WebhookContext>["webhooks"]> : Key extends "skills" ? NonNullable<NativeDefinition<unknown>["skills"]> : Key extends "dynamicSkills" ? NonNullable<NativeDefinition<unknown>["dynamicSkills"]> : Def[Key];
 };
 declare const InternalApp: unique symbol;
 /** Recognize a declaration from this framework instance before host adaptation. */

package/types/apps/src/implementation/catalog-cache.d.ts

@@ -1,6 +1,6 @@
 import { Duration, Effect, Schema } from "effect";
 import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
-import { type JsonValue } from "../contracts/schema.js";
+import { JsonObject, type JsonValue } from "../contracts/schema.js";
 export interface CatalogCacheOptions {
     /** App/build scope, optionally narrowed to the current account. */
     readonly cache?: AppCache;
@@ -11,6 +11,11 @@ export interface CatalogCacheOptions {
     /** Await a fresh revision at an explicit logical connection or refresh boundary. */
     readonly revalidate?: boolean;
 }
+/** One load: the tools, and optionally a record describing the whole catalog. */
+export interface CatalogLoad<A> {
+    readonly tools: readonly A[];
+    readonly header?: JsonObject;
+}
 export declare const catalogCache: <A extends {
     readonly name: string;
 }, S>(options: CatalogCacheOptions & {
@@ -21,9 +26,11 @@ export declare const catalogCache: <A extends {
         readonly schema: Schema.Decoder<S>;
         readonly of: (tool: A) => S;
     };
-    readonly load: (context?: CacheLoadContext) => Effect.Effect<readonly A[], unknown>;
+    readonly load: (context?: CacheLoadContext) => Effect.Effect<CatalogLoad<A>, unknown>;
 }) => Effect.Effect<{
     list: () => Effect.Effect<readonly A[], unknown, never>;
+    /** The record stored with the current revision, if the source supplied one. */
+    header: () => Effect.Effect<JsonObject | undefined, unknown>;
     summaries: () => Effect.Effect<S[], unknown, never>;
     resolve: (name: string) => Effect.Effect<A | undefined, unknown, never>;
 }, unknown, never>;

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

@@ -66,10 +66,10 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                 } | {
                     readonly type: "number" | "integer";
                     readonly default?: number;
+                    readonly maximum?: number;
                     readonly description?: string;
                     readonly title?: string;
                     readonly minimum?: number;
-                    readonly maximum?: number;
                 } | {
                     readonly type: "boolean";
                     readonly default?: boolean;

package/types/apps/src/implementation/failure-detail.d.ts

@@ -0,0 +1,25 @@
+import { Redacted } from "effect";
+import type { ResolvedAccounts } from "../contracts/host.js";
+/** Fields of `FailureDetail` as constructor input. */
+export interface FailureDetail {
+    readonly source?: "app" | "storage" | "service";
+    readonly errorName?: string;
+    readonly code?: string;
+    readonly message?: string;
+}
+/**
+ * Every credential field value of a slot-to-account record, longest first. Accepts both resolved
+ * host accounts and bound author accounts; each account keeps its credential values in `fields`.
+ */
+export declare const accountFieldSecrets: (accounts: unknown) => string[];
+/** Every credential field value of an invocation's selected accounts. */
+export declare const accountSecrets: (accounts: Redacted.Redacted<ResolvedAccounts>) => string[];
+/** Replace account secrets and bound the message for the runtime boundary. */
+export declare const boundFailureMessage: (message: string, secrets: readonly string[]) => string;
+/** `Name: message` for any thrown value, before redaction. */
+export declare const describeFailure: (error: unknown) => string;
+/**
+ * Describe what an operation raised for the app's own caller. App data failures keep their
+ * reason as a code; any other thrown value is the app's own error. Account secrets are replaced.
+ */
+export declare const failureDetail: (error: unknown, secrets: readonly string[]) => FailureDetail;

package/types/apps/src/implementation/graphql-catalog.d.ts

@@ -1,10 +1,7 @@
 import { Effect } from "effect";
 import { GraphqlToolsOptions } from "../contracts/graphql.js";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 import { type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
 export interface GraphqlCatalogOptions extends GraphqlToolsOptions, CatalogCacheOptions {
 }
-export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -1,5 +1,4 @@
 import { Effect } from "effect";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 import { McpToolsOptions } from "../contracts/mcp.js";
 import { type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
@@ -7,6 +6,4 @@ import { type OperationKinds } from "./protocol-operations.js";
 export interface McpCatalogOptions extends McpToolsOptions, CatalogCacheOptions {
 }
 /** Construction opens no transport unless explicit revalidation is requested. */
-export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -14,26 +14,42 @@ export interface WithMcpClient {
 /** Shared client operations never cache catalogs or account credentials. */
 export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError): {
     list: Effect.Effect<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly version?: string;
+            readonly name?: string;
+            readonly description?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly instructions?: string;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, ProviderError | McpError, never>;
     call: (name: string, input: JsonObject, context: McpToolContext) => Effect.Effect<{
         readonly content: readonly {
             readonly [x: string]: Schema.Json;

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

@@ -4,26 +4,42 @@ import { McpError, McpToolsOptions } from "../contracts/mcp.js";
 /** Discover and call with a fresh selected-account transport for each operation. */
 export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.Effect<void, unknown>) => Effect.Effect<{
     list: Effect.Effect<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly version?: string;
+            readonly name?: string;
+            readonly description?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly instructions?: string;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, ProviderError | McpError, never>;
     call: (name: string, input: import("../index.js").JsonObject, context: import("../mcp.js").McpToolContext) => Effect.Effect<{
         readonly content: readonly {
             readonly [x: string]: Schema.Json;

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

@@ -56,7 +56,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;
@@ -67,6 +67,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly outputSchema?: {
             readonly [x: string]: Schema.Json;
         };
+        readonly tags?: readonly string[];
         readonly operationId?: string;
         readonly streaming?: true;
         readonly errorResponses?: readonly {

package/types/apps/src/implementation/openapi-source.d.ts

@@ -3,8 +3,8 @@ import { Duration } from "effect";
 import type { AppCache } from "../contracts/cache.js";
 import { OpenapiOperation, type OpenapiToolsOptions } from "../contracts/openapi.js";
 import { JsonObject, JsonValue } from "../contracts/schema.js";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 import { type OperationKinds } from "./protocol-operations.js";
+import { type RouterDeclaration } from "./router.js";
 /** Static credential placement and destination are reviewed when the app is authored/imported. */
 export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operations" | "definitions"> {
     readonly cache: AppCache;
@@ -33,8 +33,4 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
 /** JSON-object patches are static app configuration and are reapplied to every revision. */
 export declare function patchOpenapi(root: JsonObject, patches: OpenapiSourceOptions["patches"]): JsonObject;
 /** No I/O during app construction. All accounts share credential-free compilation. */
-export declare const liveOpenapiOperations: (options: OpenapiSourceOptions) => {
-    readonly queries: {};
-    readonly mutations: {};
-    readonly dynamicTools: DynamicTools;
-};
+export declare const liveOpenapiRouter: (options: OpenapiSourceOptions) => RouterDeclaration;

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

@@ -7,16 +7,39 @@ import type { ToolAnnotations } from "../contracts/tools.js";
 import type { JsonObject } from "../contracts/schema.js";
 import { type Schema } from "./schema.js";
 declare const NativeOperation: unique symbol;
-declare const HandlerContext: unique symbol;
-/** A server-only declaration with its category preserved for catalog validation. */
+declare const QueryHandlerContext: unique symbol;
+declare const MutationHandlerContext: unique symbol;
+/**
+ * A server-only declaration with its category preserved for catalog validation. Queries and
+ * mutations carry their handler context under different phantom keys, so a router can type a
+ * query's handler from its query context alone.
+ */
 export interface OperationDeclaration<Kind extends "query" | "mutation", Context = never> {
-    readonly [HandlerContext]?: (context: Context) => void;
+    readonly [QueryHandlerContext]?: "query" extends Kind ? (context: Context) => void : never;
+    readonly [MutationHandlerContext]?: "mutation" extends Kind ? (context: Context) => void : never;
     readonly kind: Kind;
     readonly [NativeOperation]: Omit<AppOperation<never>, "kind" | "input"> & {
         readonly kind: Kind;
         readonly input: EffectSchema.Decoder<unknown>;
     };
 }
+/**
+ * A router declaration. The phantom contexts let `defineApp` type inline handlers; protocol
+ * routers accept any context because their operations only use the framework's own capabilities.
+ * The native router is held under a private key in implementation/router.ts.
+ */
+export interface RouterDeclaration<Query = unknown, Mutation = unknown> {
+    readonly [QueryHandlerContext]?: (context: Query) => void;
+    readonly [MutationHandlerContext]?: (context: Mutation) => void;
+    readonly [NativeRouterKey]: unknown;
+}
+/** An operation or nested router under one key. Each child is typed only by its own kind's context. */
+export interface RouterChild<Query, Mutation> {
+    readonly [QueryHandlerContext]?: (context: Query) => void;
+    readonly [MutationHandlerContext]?: (context: Mutation) => void;
+}
+/** Private key for a router's native definition. */
+export declare const NativeRouterKey: unique symbol;
 /** Typed operation handles drive browser reference inference without bundling handlers. */
 export interface Operation<Input, Output, Kind extends "query" | "mutation", Context = AppContext> extends OperationDeclaration<Kind, Context> {
     readonly [NativeOperation]: AppOperation<Input, Output> & {

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

@@ -17,8 +17,7 @@ interface ProtocolOperation {
     readonly run: (context: OperationContext, input: JsonValue) => Effect.Effect<unknown, unknown>;
 }
 /** Unknown behavior defaults to mutation. Classification never enforces an external service's behavior. */
-export declare const protocolOperations: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => {
-    queries: Record<string, Operation<Schema.Json, unknown, "query", OperationContext>>;
-    mutations: Record<string, Operation<Schema.Json, unknown, "mutation", OperationContext>>;
-};
+export declare const protocolOperations: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => Record<string, Operation<Schema.Json, unknown, "query" | "mutation", OperationContext>>;
+/** Operations already discovered, as a router keyed by upstream name. */
+export declare const protocolRouter: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => import("./operations.js").RouterDeclaration<unknown, unknown>;
 export {};