apps 0.0.1-beta.5 → 0.0.1-beta.7

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

@@ -3,7 +3,6 @@ import type { DatabaseDefinition } from "./storage.js";
 /** Native app contracts; factories and handlers compose in the host's Effect runtime. */
 import { type Effect, Schema } from "effect";
 import type { OperationSchedule } from "./schedules.js";
-import type { AppOperation } from "./operations.js";
 import type { AccountOf, AuthMethods, ManyAccounts, Provider } from "./provider.js";
 import type { AppWorkflow, WorkflowReads } from "./workflows.js";
 import type { Elicit } from "./elicitation.js";
@@ -11,8 +10,8 @@ import type { Elicit } from "./elicitation.js";
 type Handler<Context> = (context: Context, input: never) => Effect.Effect<unknown, unknown>;
 /** App capabilities share one account context. Package metadata belongs in package.json. */
 export interface AppDefinition<Context> {
-    /** Optional dynamic tools; resolution does not enumerate the catalog. */
-    readonly dynamicTools?: import("./dynamic-tools.js").DynamicTools;
+    /** The app's root router. Its keys form tool paths such as `issues.list`. */
+    readonly tools?: import("./router.js").AppRouter | import("./router.js").DynamicRouter;
     /** Omission reads packaged skills/. An explicit catalog replaces that default, including []. */
     readonly skills?: readonly AppSkillSource[];
     /** Optional lazy skills, added to the static catalog. Only skill reads call them. */
@@ -21,8 +20,6 @@ export interface AppDefinition<Context> {
     readonly schedules?: Readonly<Record<string, Omit<OperationSchedule, "name"> & {
         readonly tool: string;
     }>>;
-    readonly queries?: Readonly<Record<string, AppOperation>>;
-    readonly mutations?: Readonly<Record<string, AppOperation>>;
     readonly webhooks?: Readonly<Record<string, {
         readonly account: string;
         readonly config: Schema.Decoder<unknown>;

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

@@ -30,8 +30,12 @@ export { frameworkProtocol } from "./protocol-version.js";
 export { protocol1 } from "./protocols/1.js";
 export { protocol2 } from "./protocols/2.js";
 export { protocol3 } from "./protocols/3.js";
-import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/3.js";
-export { DeclaredAuthMethod, DeclaredProvider, DeclaredRequirements, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, SkillSources, SkillCatalogResponse, HostRequest, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/3.js";
+export { protocol4 } from "./protocols/4.js";
+export { protocol5, AccountCheckCommand } from "./protocols/5.js";
+export { AccountCheckResult, AccountInfo } from "./provider.js";
+import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostKindMismatch, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/5.js";
+export { DeclaredRequirements, HostRequest } from "./protocols/5.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/5.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. */
@@ -82,17 +86,24 @@ export declare const indexCommand: {
 };
 /** Keep only the requested tools from an inspection that may have described every tool. */
 export declare const selectTools: (tools?: readonly string[]) => <A extends {
-    readonly name: string;
-}>(all: readonly A[]) => readonly A[];
+    readonly tools: readonly {
+        readonly name: string;
+    }[];
+}>(catalog: A) => A;
 /** Declaration reads do not bind accounts or evaluate the app factory. A named declaration
  * problem, such as a reserved database field, is reported so the deploy can explain it. */
 export declare const HostRequirementsError: Schema.Union<readonly [typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof DatabaseFieldReserved]>;
 /** Inspection can fail while binding accounts or evaluating the live definition. */
 export declare const HostInspectError: Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>;
 /** Tool invocation adds lookup, input, execution and output failures to inspection. */
-export declare const HostCallError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostOperationFailed, typeof DatabaseLimitExceeded, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+export declare const HostCallError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostKindMismatch, typeof HostOperationFailed, typeof DatabaseLimitExceeded, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+/**
+ * An account check binds one account and runs the provider's check without evaluating the app.
+ * Timeouts arrive as WorkflowFailure from the shared deadline guard.
+ */
+export declare const HostAccountCheckError: Schema.Union<readonly [typeof ProviderError, typeof WorkflowFailure, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostOperationNotFound, typeof HostOperationFailed, typeof HostOutputInvalid]>;
 /** Queries, mutations and agent calls use the same operation failures. */
-export declare const HostDataError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostOperationFailed, typeof DatabaseLimitExceeded, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+export declare const HostDataError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostKindMismatch, typeof HostOperationFailed, typeof DatabaseLimitExceeded, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
 /** Invocation-owned outcome sink. Framework adapters report semantic failures
  * independently of successful JSON transport; customer output is never inspected. */
 export declare const ToolResultObservation: Context.Reference<{
@@ -100,5 +111,6 @@ export declare const ToolResultObservation: Context.Reference<{
 }>;
 /** Native handler; context comes from host authority, never from request content. */
 export type AppHandler = (request: Request, context: HostContext) => Effect.Effect<Response>;
-export { OperationToolPrefixes, type AppOperation, type OperationContext } from "./operations.js";
+export { type AppOperation, type OperationContext } from "./operations.js";
+export { RouterIcon, RouterKey, RouterMeta, type AppNode, type AppRouter, type DynamicRouter, } from "./router.js";
 export * from "./schedules.js";

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

@@ -63,6 +63,22 @@ export declare const McpToolMetadata: Schema.Struct<{
     readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type McpToolMetadata = typeof McpToolMetadata.Type;
+/** What a server reports about itself when a session initializes. Icons are for display only. */
+export declare const McpServerHeader: Schema.Struct<{
+    readonly name: Schema.optionalKey<Schema.String>;
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly version: Schema.optionalKey<Schema.String>;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly websiteUrl: 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 instructions: Schema.optionalKey<Schema.String>;
+}>;
+export type McpServerHeader = typeof McpServerHeader.Type;
 /** Direct callers can omit interaction capabilities. A server that asks for input then fails explicitly. */
 export interface McpToolContext {
     readonly elicit?: Elicit;

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

@@ -75,6 +75,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<{
@@ -153,6 +155,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<{

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

@@ -23,8 +23,3 @@ export interface AppOperation<Input = unknown, Output = unknown> {
     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/3.ts` and notes/apps-publishing.md.
+ * snapshot. Released protocols are frozen: see `protocols/4.ts` and notes/apps-publishing.md.
  * This file has no imports so the package build script can read it directly.
  */
-export declare const frameworkProtocol = 3;
+export declare const frameworkProtocol = 5;