apps 0.0.1-beta.2 → 0.0.1-beta.21

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

@@ -0,0 +1,225 @@
+/**
+ * Read a live router tree into tools, routers and router skills. A nested dynamic router that fails
+ * is reported on its own entry; the root failing fails the read, as a single-source app would.
+ */
+import { Effect, Schema } from "effect";
+import { HostDeclarationInvalid, HostEvaluationFailed, type HostRouterError } from "../contracts/host.js";
+import { McpError } from "../contracts/mcp.js";
+import type { AppOperation } from "../contracts/operations.js";
+import type { AppRouter, DynamicRouter, RouterMeta } from "../contracts/router.js";
+import { SkillLoadFailed } from "../contracts/skills.js";
+import type { OperationSchedule } from "../contracts/schedules.js";
+/**
+ * Keep only a failure's safe fields. Anything unrecognized becomes an evaluation failure with the
+ * error's name and bounded message, with the given account secrets replaced.
+ */
+export declare const safeFailure: (error: unknown, secrets: readonly string[]) => HostRouterError;
+/**
+ * Router skills are named `tools` for the root and `tools-<path>` below it, so a router's
+ * instructions never take an authored skill's name by accident.
+ */
+export declare const routerSkillPrefix = "tools";
+/**
+ * The skill name for a router path. A path of lowercase letters and digits is spelled out:
+ * `issues.open` is `tools-issues-open`. Any other path, or one too long, is a readable slug
+ * followed by a hash of the exact path, such as `tools-issues-list-0123456789`. Plain segments
+ * start with a letter and a hash is all digits, so the two forms never meet, and paths that slug
+ * alike, such as `issues_list` and `issues.list`, get different names.
+ */
+export declare const routerSkillName: (path: string) => string;
+/** A declared operation's catalog entry without schemas. `router` is its owning router's path. */
+export declare const operationSummary: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
+    readonly name: string;
+    readonly description: string;
+    readonly title?: string;
+    readonly annotations?: {
+        readonly title?: string;
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly idempotentHint?: boolean;
+        readonly openWorldHint?: boolean;
+    };
+    readonly schedules?: readonly {
+        readonly name: string;
+        readonly timing: {
+            readonly kind: "interval";
+            readonly milliseconds: number;
+        } | {
+            readonly kind: "cron";
+            readonly calendar: {
+                readonly expression: string;
+                readonly timezone: string;
+            };
+        };
+        readonly input: Schema.Json;
+    }[];
+    readonly readOnly?: boolean;
+    readonly router?: string;
+    readonly tags?: readonly string[];
+}, HostDeclarationInvalid, never>;
+/** A declared operation's full description, including rendered schemas. */
+export declare const operationDescription: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly _meta?: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly title?: string;
+    readonly annotations?: {
+        readonly title?: string;
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly idempotentHint?: boolean;
+        readonly openWorldHint?: boolean;
+    };
+    readonly outputSchema?: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly schedules?: readonly {
+        readonly name: string;
+        readonly timing: {
+            readonly kind: "interval";
+            readonly milliseconds: number;
+        } | {
+            readonly kind: "cron";
+            readonly calendar: {
+                readonly expression: string;
+                readonly timezone: string;
+            };
+        };
+        readonly input: Schema.Json;
+    }[];
+    readonly readOnly?: boolean;
+    readonly router?: string;
+    readonly tags?: readonly string[];
+}, HostDeclarationInvalid, never>;
+/**
+ * A dynamic router over operations already discovered, such as an eager OpenAPI document or a
+ * stdio server. Upstream names can contain dots, which static router keys cannot.
+ */
+export declare const fixedRouter: (operations: Readonly<Record<string, AppOperation>>, meta?: RouterMeta) => DynamicRouter;
+export interface CatalogOptions {
+    /** Omit schemas. */
+    readonly summary: boolean;
+    /** Account secrets that a failure's message must not reveal. */
+    readonly secrets: readonly string[];
+    /** Only these full tool names. Routers with none of them are not read. */
+    readonly wanted?: ReadonlySet<string>;
+    /** Schedules that target a declared operation, by full name. */
+    readonly schedules: (name: string) => readonly OperationSchedule[];
+    /**
+     * Only declared operations that have schedules. Schedules never target dynamic routers, and
+     * their catalogs can be expensive to discover, so none is read.
+     */
+    readonly scheduled?: true;
+}
+/**
+ * Read a router tree. Every nested router is listed, for grouping; the root only when it has
+ * metadata. A nested dynamic source that fails is reported on its router's entry.
+ */
+export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined, options: CatalogOptions) => Effect.Effect<{
+    tools: ({
+        readonly name: string;
+        readonly description: string;
+        readonly inputSchema: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly _meta?: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly title?: string;
+        readonly annotations?: {
+            readonly title?: string;
+            readonly readOnlyHint?: boolean;
+            readonly destructiveHint?: boolean;
+            readonly idempotentHint?: boolean;
+            readonly openWorldHint?: boolean;
+        };
+        readonly outputSchema?: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly schedules?: readonly {
+            readonly name: string;
+            readonly timing: {
+                readonly kind: "interval";
+                readonly milliseconds: number;
+            } | {
+                readonly kind: "cron";
+                readonly calendar: {
+                    readonly expression: string;
+                    readonly timezone: string;
+                };
+            };
+            readonly input: Schema.Json;
+        }[];
+        readonly readOnly?: boolean;
+        readonly router?: string;
+        readonly tags?: readonly string[];
+    } | {
+        readonly name: string;
+        readonly description: string;
+        readonly title?: string;
+        readonly annotations?: {
+            readonly title?: string;
+            readonly readOnlyHint?: boolean;
+            readonly destructiveHint?: boolean;
+            readonly idempotentHint?: boolean;
+            readonly openWorldHint?: boolean;
+        };
+        readonly schedules?: readonly {
+            readonly name: string;
+            readonly timing: {
+                readonly kind: "interval";
+                readonly milliseconds: number;
+            } | {
+                readonly kind: "cron";
+                readonly calendar: {
+                    readonly expression: string;
+                    readonly timezone: string;
+                };
+            };
+            readonly input: Schema.Json;
+        }[];
+        readonly readOnly?: boolean;
+        readonly router?: string;
+        readonly tags?: readonly string[];
+    })[];
+    routers: {
+        readonly path: string;
+        readonly error?: import("../index.js").ProviderError | SkillLoadFailed | McpError | HostDeclarationInvalid | HostEvaluationFailed;
+        readonly description?: string;
+        readonly title?: string;
+        readonly tags?: {
+            readonly [x: string]: string;
+        };
+        readonly icons?: readonly {
+            readonly src: string;
+            readonly mimeType?: string;
+            readonly sizes?: readonly string[];
+            readonly theme?: "light" | "dark";
+        }[];
+        readonly skill?: string;
+    }[];
+}, import("../index.js").ProviderError | SkillLoadFailed | McpError | HostDeclarationInvalid | HostEvaluationFailed, never>;
+/**
+ * One skill for each router with instructions. Skills and tools fail independently: a dynamic
+ * router whose metadata cannot be read, including the root, contributes no skill and does not
+ * fail the others. Metadata comes through each source's catalog cache, like a tool listing.
+ */
+export declare const routerSkills: (root: AppRouter | DynamicRouter | undefined) => Effect.Effect<{
+    readonly name: string;
+    readonly description: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly license?: string;
+    readonly compatibility?: string;
+    readonly metadata?: {
+        readonly [x: string]: string;
+    };
+    readonly "allowed-tools"?: string;
+}[], never, never>;

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

@@ -0,0 +1,68 @@
+import { HostedTool } from "../contracts/host.js";
+import type { AppOperation } from "../contracts/operations.js";
+import { RouterMeta, type AppRouter, type DynamicRouter, type RouterIcon } from "../contracts/router.js";
+import type { Approval } from "../approval.js";
+import { type OperationDeclaration, type RouterChild, type RouterDeclaration } from "./operations.js";
+export type { RouterChild, RouterDeclaration } from "./operations.js";
+/** Author metadata for a router. Instructions become a skill named after the router's path. */
+export interface RouterOptions {
+    readonly title?: string;
+    readonly description?: string;
+    readonly instructions?: string;
+    readonly icons?: readonly RouterIcon[];
+    readonly tags?: Readonly<Record<string, string>>;
+}
+/** Wrap a native router. Protocol helpers use this for the routers they build. */
+export declare const routerDeclaration: (node: AppRouter | DynamicRouter) => RouterDeclaration;
+/** Accept only framework-created routers. */
+export declare const nativeRouter: (value: unknown) => AppRouter | DynamicRouter | undefined;
+/** Author fields win; a field the author omits keeps the source's value. */
+export declare const mergeMeta: (base: RouterMeta | undefined, override: RouterMeta | undefined) => RouterMeta | undefined;
+/**
+ * Group operations and routers under path keys, like tRPC's nested routers, with metadata an
+ * agent can read. Passing an existing router instead of children overrides its metadata:
+ * `router(mcpRouter(options), { description: "..." })`.
+ */
+export declare function router<Query = unknown, Mutation = unknown>(children: Readonly<Record<string, RouterChild<Query, Mutation>>>, options?: RouterOptions): RouterDeclaration<Query, Mutation>;
+export declare function router<Query, Mutation>(source: RouterDeclaration<Query, Mutation>, options: RouterOptions): RouterDeclaration<Query, Mutation>;
+/**
+ * Declare a router whose tools are discovered when read. `list` returns tools with names relative
+ * to this router; mark queries with `readOnly: true`. `resolve` receives one of those names.
+ */
+export declare const dynamicRouter: (source: {
+    readonly meta?: () => RouterOptions | Promise<RouterOptions>;
+    readonly list: () => readonly HostedTool[] | Promise<readonly HostedTool[]>;
+    readonly resolve: (name: string) => OperationDeclaration<"query" | "mutation", unknown> | undefined | Promise<OperationDeclaration<"query" | "mutation", unknown> | undefined>;
+}) => RouterDeclaration;
+/** Join a router path and a relative name. The root router's path is "". */
+export declare const joinPath: (path: string, name: string) => string;
+/** Where a full tool name points: a declared operation, or a name inside a dynamic router. */
+export type Location = {
+    readonly kind: "operation";
+    readonly operation: AppOperation;
+    readonly router: string;
+} | {
+    readonly kind: "dynamic";
+    readonly source: DynamicRouter;
+    readonly router: string;
+    readonly name: string;
+};
+/**
+ * Walk static keys until the name ends at an operation or enters a dynamic router, which receives
+ * the rest of the name. Static keys contain no dots, so every name has at most one location.
+ */
+export declare const locate: (root: AppRouter | DynamicRouter | undefined, name: string) => Location | undefined;
+/** Every declared operation with its full name and owning router. Dynamic routers are not listed. */
+export declare const declaredOperations: (root: AppRouter | undefined, path?: string) => Array<{
+    readonly name: string;
+    readonly router: string;
+    readonly operation: AppOperation;
+}>;
+/**
+ * Choose an approval for each operation a router contains, including tools a dynamic router
+ * resolves later. `policy` receives the operation and its name relative to this router; returning
+ * undefined keeps the operation's own approval. Read hints with `toolAnnotations(operation)`.
+ * Apply it to each account's router before `accountRouter` combines them, so every account keeps
+ * its own tools' hints.
+ */
+export declare const withApprovals: <Query, Mutation>(source: RouterDeclaration<Query, Mutation>, policy: (operation: OperationDeclaration<"query" | "mutation", never>, name: string) => Approval | undefined) => RouterDeclaration<Query, Mutation>;

package/types/apps/src/implementation/runtime-yield.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Let the runtime run its own tasks between long synchronous steps. In a Worker, a large OpenAPI
+ * compilation that never yields leaves the garbage collector only long, full pauses; yielding
+ * between steps measurably shortens it. A timer is used because a resolved promise would continue
+ * without leaving the current task.
+ */
+export declare const yieldToRuntime: () => Promise<void>;

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

@@ -1,7 +1,8 @@
 /** Author schema facade. Internals use the native decoder retained by each value. */
 import { Effect, Schema as EffectSchema } from "effect";
-import { ValidationError, type JsonObject } from "../contracts/schema.js";
+import { JsonObject, ValidationError } from "../contracts/schema.js";
 import type { Field } from "../../../app-data/src/contracts/database.js";
+import type { FieldExposure } from "../contracts/provider.js";
 declare const StorageField: unique symbol;
 declare const Decoder: unique symbol;
 /** An author-facing value schema. Effect is never required in author code. */
@@ -59,6 +60,44 @@ export declare function literal<const T extends string | number | boolean | null
 export declare const array: <T>(item: Schema<T, boolean>) => Schema<readonly T[]>;
 /** Parse declared fields and omit undeclared fields. */
 export declare function object<const F extends Fields>(fields: F): ObjectSchema<F>;
+declare const Exposure: unique symbol;
+/** A schema marked with how app code sees the field in a provider that declares hosts. */
+export type Exposed<S, E extends FieldExposure = FieldExposure> = S & {
+    readonly [Exposure]: E;
+};
+/** The marking of one account field, if any. */
+export declare const exposureOf: (schema: Schema<unknown, boolean>) => FieldExposure | undefined;
+/**
+ * A field that is not secret, such as a subdomain or region. App code reads its real value and
+ * the connect form shows it.
+ */
+export declare const plain: <S extends Schema<unknown, boolean>>(schema: S) => Exposed<S, "plain">;
+/**
+ * A secret field that app code reads as its real value, for request signing and similar uses.
+ * The connect form warns that the app can read it. Prefer an unmarked field, which app code
+ * receives as a handle that only reaches the provider's declared hosts.
+ */
+export declare const raw: <S extends Schema<unknown, boolean>>(schema: S) => Exposed<S, "raw">;
+/** Marked fields of an account object, by name. */
+export declare const fieldExposure: (fields: Fields) => Readonly<Record<string, FieldExposure>>;
+declare const Secret: unique symbol;
+/**
+ * A secret account value. In a provider that declares hosts it is a handle, which the host's
+ * outbound network replaces with the real value only on requests to those hosts. Pass it to
+ * clients and headers as an ordinary string; do not decode or transform it.
+ */
+export type SecretString = string & {
+    readonly [Secret]: true;
+};
+type Sealed<T> = T extends string ? SecretString : T;
+/** Account fields as app code receives them: unmarked string fields are secret. */
+export type SecretFields<F extends Fields> = {
+    readonly [Key in keyof ObjectValue<F>]: Key extends keyof F ? F[Key] extends Exposed<unknown> ? ObjectValue<F>[Key] : Sealed<ObjectValue<F>[Key]> : ObjectValue<F>[Key];
+};
+/** An account object without declared fields, such as a default OAuth projection. */
+export type SecretObject<T> = {
+    readonly [Key in keyof T]: Sealed<T[Key]>;
+};
 declare const ImportedJsonSchema: unique symbol;
 /** Read the original document for an imported decoder without a lossy schema round trip. */
 export declare const importedJsonSchema: (decoder: EffectSchema.Decoder<unknown>) => unknown | undefined;
@@ -91,4 +130,8 @@ export declare const storageFieldOf: (schema: Schema<unknown, boolean>) => Field
 export declare const id: (table: string) => Schema<string>;
 /** A host user identifier, stored as a string without imposing a product auth model. */
 export declare const userId: () => Schema<string>;
+/** Render a decoder as a JSON Schema document, keeping an imported upstream document as-is. */
+export declare const jsonSchemaDocument: (decoder: EffectSchema.Decoder<unknown>) => Effect.Effect<{
+    readonly [x: string]: EffectSchema.Json;
+}, EffectSchema.SchemaError, never>;
 export {};

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

@@ -1,10 +1,12 @@
-import { type DatabaseSession } from "../../../app-data/src/index.js";
+import { type DatabaseSession, type reservedFieldNames } from "../../../app-data/src/index.js";
+type ReservedFieldName = (typeof reservedFieldNames)[number];
 import { type AppStorage } from "../contracts/storage.js";
 import type { DatabaseDefinition, Database, Table, Tables } from "../contracts/storage.js";
 import { type Fields } from "./schema.js";
 export type { DatabaseDefinition, Database, DatabaseReader, Table, Tables, RowOf, } from "../contracts/storage.js";
-/** Declare scalar columns using the same schemas as operation inputs. */
-export declare const table: <const F extends Fields>(fields: F) => Table<F>;
+/** Declare scalar columns using the same schemas as operation inputs. The host adds `id`,
+ * `createdAt` and `updatedAt` to every row, so tables cannot declare those names. */
+export declare const table: <const F extends Fields & { readonly [K in ReservedFieldName]?: never; }>(fields: F) => Table<F>;
 /** Build a fresh Promise database facade for one authorized invocation. */
 export declare const authorDatabase: <T extends Tables>(tables: T, session: DatabaseSession, signal: AbortSignal, writable: boolean) => Database<T>;
 /** Declare storage independently of handlers; the host binds each invocation's database. */

package/types/apps/src/implementation/ui-account-notice.d.ts

@@ -0,0 +1,9 @@
+/** Host-rendered account notices; no authored app code or provider responses enter them. */
+import type { UiAccountNotice, UiAccountProblem } from "../contracts/ui.js";
+/** Missing, removed, incompatible, or rejected accounts stop the app; other failed checks are advisory. */
+export declare const accountProblemBlocks: (problem: UiAccountProblem) => boolean;
+export declare const accountProblemText: (problem: UiAccountProblem) => string;
+/** Full page shown instead of the app while an account problem stops it from working. */
+export declare const accountBlockedPage: (notice: UiAccountNotice) => string;
+/** Inline card for advisory problems; the app still loads underneath. */
+export declare const accountNoticeBootstrap: (notice: UiAccountNotice) => string;

package/types/apps/src/implementation/ui-auth.d.ts

@@ -1,5 +1,6 @@
-/** Trusted bootstrap documents run before authored UI and never contain product credentials. */
+/** Host responses around app sign-in. They carry no script and never contain product credentials. */
 import { HttpServerResponse } from "effect/unstable/http";
+import { type AppSignInId } from "../contracts/ui-auth.js";
 /** Private app responses must not leak authentication URLs through caches or referrers. */
 export declare const appPrivateHeaders: {
     "cache-control": string;
@@ -7,7 +8,12 @@ export declare const appPrivateHeaders: {
     "x-content-type-options": string;
     "content-security-policy": string;
 };
-/** Serve only a fixed host script while authentication runs; the original URL remains available to that script. */
-export declare const appSignInPage: () => HttpServerResponse.HttpServerResponse;
-/** Preserve deep links, erase callback proofs before any request, and let the host set HttpOnly cookies. */
-export declare const appSignInScript: () => HttpServerResponse.HttpServerResponse;
+/** Every sign-in hop is a server redirect, so the browser paints nothing until the app itself. */
+export declare const appRedirect: (url: string) => HttpServerResponse.HttpServerResponse;
+/**
+ * The callback URL carries the code in its query. It exists only as a redirect `Location`, never as
+ * a rendered document, and redeeming it also requires the attempt's HttpOnly cookie.
+ */
+export declare const appSignInCallback: (origin: string, request: AppSignInId, code: string) => string;
+/** A failed callback explains itself without script; reopening the app URL starts a new attempt. */
+export declare const appSignInFailed: () => HttpServerResponse.HttpServerResponse;

package/types/apps/src/implementation/ui-errors.d.ts

@@ -1,2 +1,2 @@
 /** Inline host script: no app dependencies, credentials, or authored HTML enter its source. */
-export declare const appFailureBootstrap: string;
+export declare const appFailureBootstrap = "<script>\"use strict\";(()=>{var D=()=>{let d,w=Date.now(),m=0,g=0,f=new Map,A=/^(?:chrome|moz|safari-web)-extension:/,R=new Set([\"Error\",\"TypeError\",\"ReferenceError\",\"SyntaxError\",\"RangeError\",\"URIError\",\"EvalError\",\"AggregateError\"]),x=(e,t=0,i=0)=>{let r=[];if(!URL.canParse(e))return r;let a=new URL(e);return a.origin!==location.origin||!a.pathname.startsWith(\"/_executor/assets/\")||!a.pathname.endsWith(\".js\")||(r.push({key:\"code.file.path\",value:{stringValue:a.pathname}}),Number.isSafeInteger(t)&&t>0&&r.push({key:\"code.line.number\",value:{intValue:String(t)}}),Number.isSafeInteger(i)&&i>0&&r.push({key:\"code.column.number\",value:{intValue:String(i)}})),r},E=(e,t,i=[])=>{let r=Date.now();r-w>=6e4&&(w=r,m=0,f.clear());let a=`${e}:${t.slice(0,2e3)}`,b=f.get(a);if(b!==void 0&&r-b<1e3||m>=20){g++;return}f.set(a,r),m++,i.push({key:\"executor.ui.failure.suppressed\",value:{intValue:String(g)}}),g=0;let h=Array.from(crypto.getRandomValues(new Uint8Array(16)),s=>s.toString(16).padStart(2,\"0\")).join(\"\"),S=`${Date.now()}000000`,n,u=\"Sending error report\\u2026\",k=()=>{if(d?.open)return;let s=document.createElement(\"div\"),V=s.attachShadow({mode:\"open\"}),o=document.createElement(\"dialog\");d=o,o.setAttribute(\"aria-labelledby\",\"executor-failure-title\");let y=document.createElement(\"h2\");y.id=\"executor-failure-title\",y.textContent=e===\"script\"?\"This app could not load\":\"This app stopped working\";let C=document.createElement(\"p\");C.textContent=e===\"script\"?\"A file needed by this page did not load. Reload the page to try again.\":\"The app encountered an unexpected error. Reload the page to try again.\";let L=document.createElement(\"p\");L.textContent=\"Copy any unsaved work before reloading.\";let T=document.createElement(\"details\"),v=document.createElement(\"summary\");v.textContent=\"Error details\";let c=document.createElement(\"textarea\");c.readOnly=!0,c.rows=10,c.cols=36,c.setAttribute(\"aria-label\",\"Error details\"),c.value=`${t.slice(0,12e3)}\n\nDiagnostic ID: ${h}`,T.append(v,c),n=document.createElement(\"p\"),n.setAttribute(\"role\",\"status\"),n.textContent=u;let l=document.createElement(\"button\");l.type=\"button\",l.textContent=\"Reload page\",l.addEventListener(\"click\",()=>location.reload());let p=document.createElement(\"button\");p.type=\"button\",p.textContent=\"Close\",p.addEventListener(\"click\",()=>o.close()),o.addEventListener(\"close\",()=>{d===o&&(d=void 0),s.remove()}),o.append(y,C,L,T,n,l,p),V.append(o),document.documentElement.append(s),o.showModal()};document.readyState===\"loading\"?document.addEventListener(\"DOMContentLoaded\",k,{once:!0}):k(),fetch(\"/_executor/api/telemetry/traces\",{method:\"POST\",headers:{\"content-type\":\"application/json\"},credentials:\"same-origin\",keepalive:!0,body:JSON.stringify({resourceSpans:[{scopeSpans:[{spans:[{traceId:h,spanId:h.slice(0,16),name:\"ui.app.failure\",kind:1,startTimeUnixNano:S,endTimeUnixNano:S,status:{code:2},attributes:[{key:\"executor.ui.failure.kind\",value:{stringValue:e}},...i]}]}]}]})}).then(s=>{u=s.ok?\"Error report sent.\":\"Could not send the error report. You can copy the error details.\",n&&(n.textContent=u)},()=>{u=\"Could not send the error report. You can copy the error details.\",n&&(n.textContent=u)})};window.addEventListener(\"error\",e=>{if(e instanceof ErrorEvent){if(A.test(e.filename))return;let t=x(e.filename,e.lineno,e.colno);e.error instanceof Error&&R.has(e.error.name)&&t.push({key:\"exception.type\",value:{stringValue:e.error.name}}),E(\"runtime\",e.error instanceof Error?e.error.stack??e.message:e.message,t)}else e.target instanceof HTMLScriptElement&&E(\"script\",`Could not load script: ${e.target.src}`,x(e.target.src))},!0),window.addEventListener(\"unhandledrejection\",e=>{let t=e.reason;E(\"rejection\",t instanceof Error?t.stack??t.message:\"An app operation failed without handling its error.\")})};D();})();</script>";

package/types/apps/src/implementation/ui-serving.d.ts

@@ -1,16 +1,22 @@
 import { Effect } from "effect";
 import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
-import { UiForbidden, type AppUiAsset } from "../contracts/ui.js";
-/** Render an authorized deployment with a host-owned deployment watcher. */
+import { UiForbidden, type AppUiAsset, type UiAccountNotice } from "../contracts/ui.js";
+/**
+ * Render an authorized deployment with a host-owned deployment watcher. Account problems that stop
+ * the app replace its document with a page that links to their fix; others add a dismissible card.
+ */
 export declare const appDocument: <E, R>(options: {
     readonly deployment: string;
     readonly profile?: string | undefined;
     readonly expectedProfileRevision?: number | undefined;
     readonly origin: string;
+    readonly accounts?: UiAccountNotice | undefined;
     readonly asset: (path: string) => Effect.Effect<AppUiAsset | undefined, E, R>;
 }) => Effect.Effect<HttpServerResponse.HttpServerResponse, UiForbidden | E, HttpServerRequest.HttpServerRequest | R>;
-/** Revalidate immutable assets only after the host has checked current access and file existence.
- * Browsers may retain bytes, but neither browsers nor shared proxies may reuse them without authorization.
+/** Serve an asset only after the host has checked current access and file existence.
+ * Asset URLs name their deployment, so their bytes never change: the browser keeps them for a year
+ * and does not ask again. Shared proxies never store them. Revoking access stops every new request
+ * and all app data, while bytes a browser already downloaded stay in its cache.
  * HTML remains an uncached host-rendered entry point.
  */
 export declare const appAsset: (asset: AppUiAsset | undefined, build: string, path: string) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, HttpServerRequest.HttpServerRequest>;

package/types/apps/src/implementation/ui-watch.d.ts

@@ -1,2 +1,2 @@
 /** Dependency-free browser source served by each host after app authorization. */
-export declare const appWatchScript: string;
+export declare const appWatchScript = "\"use strict\";(()=>{var s=()=>{let i=document.getElementById(\"executor-context\")?.textContent;if(!i)return;let n=JSON.parse(i);if(typeof n!=\"object\"||n===null||!(\"deployment\"in n))return;let r=n.deployment;if(typeof r!=\"string\"||r.length===0)return;let t=new EventSource(\"/_executor/version\"),l=!1,o=()=>{l||(l=!0,t.close(),location.reload())};t.addEventListener(\"version\",d=>{let e=JSON.parse(d.data);typeof e==\"object\"&&e!==null&&\"deployment\"in e&&(e.deployment===null||typeof e.deployment==\"string\")&&e.deployment!==r&&o()}),t.addEventListener(\"revoked\",o),window.addEventListener(\"executor:deployment-changed\",o),window.addEventListener(\"pagehide\",()=>t.close(),{once:!0}),window.addEventListener(\"pageshow\",d=>{d.persisted&&o()})};s();})();";

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

@@ -26,4 +26,4 @@ export declare const dispatchWebhook: <Context extends {
         readonly [x: string]: string;
     };
     readonly body: string;
-}, HostDeclarationInvalid | HostOperationNotFound | HostOperationFailed | HostInputInvalid | HostOutputInvalid, never>;
+}, HostOperationNotFound | HostInputInvalid | HostOutputInvalid | HostDeclarationInvalid | HostOperationFailed, never>;

package/types/apps/src/implementation/workflow-context.d.ts

@@ -2,7 +2,15 @@
 import { Effect } from "effect";
 import type { AppDefinition } from "../contracts/app.js";
 import { WorkflowFailure, type WorkflowContext, type WorkflowExecution, type WorkflowStepContext } from "../contracts/workflows.js";
-/** Preserve typed failures and cancellation; authored exception text never leaves the app. */
-export declare const workflowSafe: <A>(work: Effect.Effect<A, unknown>) => Effect.Effect<A, WorkflowFailure>;
+/**
+ * Preserve typed failures and cancellation. Other errors keep their name and bounded message,
+ * with the given account secrets replaced.
+ */
+export declare const workflowSafe: <A>(work: Effect.Effect<A, unknown>, secrets: readonly string[]) => Effect.Effect<A, WorkflowFailure>;
 /** Construct one replay's Promise context. Step callbacks acquire fresh capabilities per actual attempt. */
-export declare const makeWorkflowContext: (execution: WorkflowExecution, definition: Pick<AppDefinition<never>, "queries" | "mutations">, fresh: (stepId: string, signal: AbortSignal) => Effect.Effect<WorkflowStepContext, WorkflowFailure>, signal: AbortSignal) => Effect.Effect<WorkflowContext>;
+export declare const makeWorkflowContext: (execution: WorkflowExecution, definition: Pick<AppDefinition<never>, "tools">, 
+/** A step attempt's context, and the raw account secrets its failures must not reveal. */
+fresh: (stepId: string, signal: AbortSignal) => Effect.Effect<{
+    readonly context: WorkflowStepContext;
+    readonly secrets: readonly string[];
+}, WorkflowFailure>, signal: AbortSignal) => Effect.Effect<WorkflowContext>;

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

@@ -8,32 +8,49 @@ export { CacheError } from "../../app-cache/src/contracts/cache.js";
 import { type Schema as EffectSchema } from "effect";
 import type { WebhookContext } from "./contracts/context.js";
 import { type JsonResponse as NativeResponse } from "./contracts/http.js";
-import { type OAuth2Config, type OAuth2Method as NativeOAuth2Method, type SecretsMethod as NativeSecretsMethod } from "./contracts/provider.js";
+import { type OAuth2Config as NativeOAuth2Config, type OAuth2Method as NativeOAuth2Method, type ReservedAuthorizationParam, type SecretsMethod as NativeSecretsMethod } from "./contracts/provider.js";
 import type { Webhook as NativeWebhook } from "./contracts/webhooks.js";
 import { type PromiseMethods } from "./implementation/authoring.js";
-import { type Fields, type Infer, type ObjectSchema, type Schema } from "./implementation/schema.js";
+import { type Fields, type Infer, type ObjectSchema, type Schema, type SecretFields, type SecretObject } from "./implementation/schema.js";
 export { type JsonObject, type JsonValue, ValidationError } from "./contracts/schema.js";
-export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Schema, array, boolean, json, jsonSchema, literal, number, object, record, string, } from "./implementation/schema.js";
-export { type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type OAuth2Config, type Provider, } from "./contracts/provider.js";
-export { defineProvider } from "./implementation/provider.js";
-export { accountOperations } from "./implementation/account-operations.js";
-export { dynamicTools } from "./implementation/dynamic-tools.js";
+export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Schema, array, boolean, json, jsonSchema, literal, number, object, record, string, plain, raw, type SecretString, } from "./implementation/schema.js";
+export { type AccountCheckContext, type AccountCheckResult, type AccountInfo, type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type Provider, type ReservedAuthorizationParam, } from "./contracts/provider.js";
+export { defineProvider, type ProviderOptions } from "./implementation/provider.js";
+export { accountRouter } from "./implementation/account-router.js";
+export { router, dynamicRouter, withApprovals, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
+export type { RouterIcon } from "./contracts/router.js";
 export { dynamicSkills } from "./implementation/dynamic-skills.js";
 export type { HostedTool as OperationDescription } from "./contracts/host.js";
+/** Account fields as app code receives them from a method declared with this schema. */
+type AccountFields<S> = S extends ObjectSchema<infer F> ? SecretFields<F> : SecretObject<Infer<S>>;
 /** A secrets declaration inferred from an author schema. */
-export type SecretsMethod<Shape extends ObjectSchema<Fields>> = NativeSecretsMethod<EffectSchema.Decoder<Infer<Shape>>>;
+export type SecretsMethod<Shape extends ObjectSchema<Fields>> = NativeSecretsMethod<EffectSchema.Decoder<AccountFields<Shape>>>;
 /** An OAuth declaration inferred from its author-facing response schema. */
-export type OAuth2Method<Response extends Schema<unknown, boolean>> = NativeOAuth2Method<EffectSchema.Decoder<Infer<Response>>>;
+export type OAuth2Method<Response extends Schema<unknown, boolean>> = NativeOAuth2Method<EffectSchema.Decoder<AccountFields<Response>>>;
 /** Default OAuth fields visible to app code. Host-only grants and clients stay private. */
 export declare const OAuth2AccessToken: Schema<{
     readonly access_token: string;
 }, false>;
+/**
+ * OAuth options as authors write them. `authorizationParams` naming a host-owned protocol
+ * parameter such as `state` or `scope` is a type error as well as a declaration failure.
+ */
+export type OAuth2Config = WithoutReservedParams<NativeOAuth2Config>;
+type WithoutReservedParams<Config> = Config extends unknown ? "authorizationParams" extends keyof Config ? Config & {
+    readonly authorizationParams?: {
+        readonly [Key in ReservedAuthorizationParam]?: never;
+    };
+} : Config : never;
 /** Declare a secrets method without requiring an Effect schema from the author. */
 export declare const secrets: <const F extends Fields>(options: {
     readonly label: string;
     readonly fields: ObjectSchema<F>;
 }) => SecretsMethod<ObjectSchema<F>>;
-/** Declare OAuth discovery/endpoints and an optional app-visible response projection. */
+/**
+ * Declare OAuth discovery/endpoints and an optional app-visible response projection.
+ * `authorizationParams` adds service-defined sign-in parameters; a declared `authorizationUrl`
+ * keeps its own query. Neither can set host-owned parameters, and each parameter appears once.
+ */
 export declare function oauth2(options: OAuth2Config): OAuth2Method<typeof OAuth2AccessToken>;
 export declare function oauth2<Response extends Schema<unknown, boolean>>(options: OAuth2Config & {
     readonly response: Response;
@@ -57,7 +74,7 @@ export { NotImplemented } from "./contracts/app.js";
 export { ElicitationFailed, type FormElicitation, type ElicitationResponse, type Elicit, } from "./contracts/elicitation.js";
 export { table, defineDatabase, type Table, type DatabaseReader, type Database, type DatabaseDefinition, } from "./implementation/storage.js";
 export { id, userId } from "./implementation/schema.js";
-export { query, mutation, withApproval, type Operation, type OperationOptions, } from "./implementation/operations.js";
+export { query, mutation, withApproval, toolAnnotations, type Operation, type OperationOptions, } from "./implementation/operations.js";
 export type { OperationContext } from "./contracts/operations.js";
 export { workflow, type Workflow, type WorkflowDeclaration } from "./implementation/workflows.js";
 export { NonRetryableError, WorkflowFailure, type WorkflowContext, type WorkflowStepContext, type WorkflowStep, type WorkflowStepOptions, type WorkflowDuration, type WorkflowReads, type WorkflowControls, } from "./contracts/workflows.js";

package/types/apps/src/mcp-stdio.d.ts

@@ -1,8 +1,5 @@
 import type { ProcessConfig } from "./contracts/mcp.js";
 import { type OperationKinds } from "./implementation/protocol-operations.js";
 export { McpError, type McpToolContext, type ProcessConfig } from "./contracts/mcp.js";
-/** Discover an account's tools; each discovery and call owns and closes its subprocess. */
-export declare const stdioOperations: (config: ProcessConfig, signal?: AbortSignal, kinds?: OperationKinds) => Promise<{
-    queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
-    mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
-}>;
+/** Discover an account's tools as a router; each discovery and call owns and closes its subprocess. */
+export declare const stdioRouter: (config: ProcessConfig, signal?: AbortSignal, kinds?: OperationKinds) => Promise<import("./index.js").RouterDeclaration<unknown, unknown>>;

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

@@ -3,8 +3,9 @@ import type { OperationKinds } from "./implementation/protocol-operations.js";
 import { type McpCatalogOptions } from "./implementation/mcp-catalog.js";
 export type { McpCatalogOptions } from "./implementation/mcp-catalog.js";
 export { McpError, type McpToolContext, type McpToolsOptions, type McpToolResult, } from "./contracts/mcp.js";
-/** Discover operations for the selected account. Kinds override uncertain upstream read-only hints. */
-export declare const mcpOperations: (options: McpCatalogOptions, kinds?: OperationKinds) => Promise<{
-    dynamicTools: import("./contracts/dynamic-tools.js").DynamicTools;
-}>;
+/**
+ * A router over a server's tools for the selected account. Its title, description and
+ * instructions come from the server. Kinds override uncertain upstream read-only hints.
+ */
+export declare const mcpRouter: (options: McpCatalogOptions, kinds?: OperationKinds) => Promise<import("./index.js").RouterDeclaration<unknown, unknown>>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";

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

@@ -2,11 +2,11 @@
 import { type OperationKinds } from "./implementation/protocol-operations.js";
 import type { OpenapiToolsOptions } from "./contracts/openapi.js";
 export { OpenapiError, isOpenapiTextMedia, openapiBinaryResultSchema, OpenapiErrorResponse, type OpenapiToolsOptions, type OpenapiOperation, type CredentialBinding, OpenapiParameter, OpenapiRequestBody, openapiMediaKind, } from "./contracts/openapi.js";
-/** Discover operations for the selected account. Kinds override uncertain upstream read-only hints. */
-export declare const openapiOperations: (options: OpenapiToolsOptions, kinds?: OperationKinds) => Promise<{
-    queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
-    mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
-}>;
+/**
+ * Discover a document's operations as a router for the selected account. Kinds override uncertain
+ * upstream read-only hints. Mount it under a key, or override its metadata with `router(...)`.
+ */
+export declare const openapiRouter: (options: OpenapiToolsOptions, kinds?: OperationKinds) => Promise<import("./index.js").RouterDeclaration<unknown, unknown>>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";
 export * from "./contracts/openapi-compile.js";
-export { liveOpenapiOperations, type OpenapiSourceOptions, } from "./implementation/openapi-source.js";
+export { liveOpenapiRouter, type OpenapiSourceOptions } from "./implementation/openapi-source.js";

package/types/apps/src/ui-auth.d.ts

@@ -1,3 +1,3 @@
-/** Host-only app authentication protocol and bootstrap; products supply identity and session lifecycle. */
+/** Host-only app authentication protocol; products supply identity and session lifecycle. */
 export * from "./contracts/ui-auth.js";
-export { appPrivateHeaders, appSignInPage, appSignInScript } from "./implementation/ui-auth.js";
+export { appPrivateHeaders, appRedirect, appSignInCallback, appSignInFailed, } from "./implementation/ui-auth.js";