apps 0.0.1-beta.1 → 0.0.1-beta.100

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

@@ -0,0 +1,71 @@
+/**
+ * `ctx.sql` over a data facet's SQLite storage, and the deploy-time migrator.
+ *
+ * Every statement runs inside a synchronous SQLite transaction: alone, or inside the author's
+ * `transaction`. Nothing here can wait on another call, so no lock or transaction outlives the
+ * statement that needs it. What a statement may do is decided by SQLite, not by reading the SQL:
+ * a query runs in a transaction that is always rolled back.
+ */
+import { Effect, Schema } from "effect";
+import { type AppSqlStorage, type Sql, type SqlReader } from "../contracts/sql.js";
+import type { SkillFile } from "../contracts/skills.js";
+export declare const noDatabase: Sql;
+/** A workflow step mutation's identity, from the host's replay record. */
+export interface StepReplay {
+    readonly key: string;
+    readonly fingerprint: string;
+}
+/**
+ * One invocation's SQL. Once the invocation ends or `signal` aborts, every statement is refused, so
+ * code still running after a timeout or cancellation cannot write late.
+ */
+export declare const authorSql: (storage: AppSqlStorage, options: {
+    readonly signal: AbortSignal;
+    readonly step?: StepReplay;
+    /**
+     * The invocation's emitted events. A transaction that rolls back also discards the events its
+     * callback emitted, so subscribers never hear of writes that did not commit.
+     */
+    readonly emitted?: unknown[];
+}) => {
+    reader: SqlReader;
+    writer: Sql;
+    close: () => void;
+};
+declare const MigrationFileInvalid_base: Schema.Class<MigrationFileInvalid, Schema.TaggedStruct<"MigrationFileInvalid", {
+    readonly path: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A file in `migrations/` that is not a migration the host can order. */
+export declare class MigrationFileInvalid extends MigrationFileInvalid_base {
+    get message(): string;
+}
+declare const MigrationHistoryChanged_base: Schema.Class<MigrationHistoryChanged, Schema.TaggedStruct<"MigrationHistoryChanged", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The build's migrations no longer start with the ones already applied to the database. */
+export declare class MigrationHistoryChanged extends MigrationHistoryChanged_base {
+    get message(): string;
+}
+declare const MigrationFailed_base: Schema.Class<MigrationFailed, Schema.TaggedStruct<"MigrationFailed", {
+    readonly path: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** SQLite rejected a migration. Every migration of the deploy rolled back. */
+export declare class MigrationFailed extends MigrationFailed_base {
+    get message(): string;
+}
+/** Whether a build's files give the app a database: any `.sql` file in `migrations/`. */
+export declare const hasMigrations: (files: readonly {
+    readonly path: string;
+}[]) => boolean;
+/**
+ * Apply the build's pending migrations and report which ran. Every pending migration runs in one
+ * transaction, so a failing one leaves the database exactly as the active version knows it. The
+ * migrations already applied must still be the build's first ones, byte for byte.
+ */
+export declare const migrate: (storage: AppSqlStorage, files: readonly SkillFile[]) => Effect.Effect<{
+    readonly id: number;
+    readonly name: string;
+}[], MigrationFileInvalid | MigrationHistoryChanged | MigrationFailed, never>;
+export {};

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

@@ -0,0 +1,28 @@
+/** Swagger is most of the OpenAPI module's code. Discovery from a cached catalog never needs it,
+ * so a cold app Worker evaluates it only when it resolves a document or builds a request.
+ */
+import "../contracts/swagger-client.ts";
+export type SwaggerClient = typeof import("swagger-client").default;
+export declare const loadSwaggerClient: () => Promise<{
+    buildRequest(options: {
+        spec: unknown;
+        operationId?: string;
+        pathName?: string;
+        method?: string;
+        parameters?: Readonly<Record<string, unknown>>;
+        requestBody?: unknown;
+        requestContentType?: string;
+        securities?: {
+            authorized: Readonly<Record<string, unknown>>;
+        };
+    }): unknown;
+    resolve(options: {
+        spec: unknown;
+        skipNormalization: boolean;
+        useCircularStructures: boolean;
+        requestInterceptor: () => never;
+    }): Promise<{
+        spec: unknown;
+        errors: readonly unknown[];
+    }>;
+}>;

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. */
-import { HttpServerResponse } from "effect/unstable/http";
+/** Host responses around app sign-in. They carry no script and never contain product credentials. */
+import { HttpServerResponse } from "effect/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-client.d.ts

@@ -1,7 +1,7 @@
-import { Atom } from "effect/unstable/reactivity";
+import { AsyncResult, Atom } from "effect/reactivity";
 import { type OperationReference } from "../contracts/live.js";
 import { type Schema } from "./schema.js";
-/** A scoped page client. Host-injected context carries only the deployment, never credentials. */
+/** A scoped page client. Host-injected context carries only the version, never credentials. */
 export declare const createAppClient: () => {
     /** Close this client when its page or embedding owner is removed. */
     dispose: () => Promise<void>;
@@ -12,5 +12,5 @@ export declare const createAppClient: () => {
     /** Create a callable mutation with optional withOptimisticUpdate projections over mounted queries. */
     mutation: <Input, Output>(reference: OperationReference<Input, Output, "mutation">, output: Schema<NoInfer<Output>, boolean>) => import("../client.js").AppMutation<Input, Output>;
     /** Share a live query across mounts and reconcile optimistic changes against fresh server reads. */
-    queryAtom: <Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, output: Schema<NoInfer<Output>, boolean>) => Atom.Atom<import("effect/unstable/reactivity/AsyncResult").AsyncResult<Output, unknown>>;
+    queryAtom: <Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, output: Schema<NoInfer<Output>, boolean>) => Atom.Atom<AsyncResult.AsyncResult<Output, unknown>>;
 };

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

@@ -0,0 +1,5 @@
+/**
+ * Retained files sit at the version's asset root. Resolving path-relative resource URLs there,
+ * instead of with `<base>`, leaves the document base as the page URL for links, history and forms.
+ */
+export declare const versionDocument: (html: string, version: string) => string;

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 M=()=>{let d,w=Date.now(),m=0,g=0,f=new Map,v=/^(?:chrome|moz|safari-web)-extension:/,A=new Set([\"ResizeObserver loop completed with undelivered notifications.\",\"ResizeObserver loop limit exceeded\"]),V=new Set([\"Error\",\"TypeError\",\"ReferenceError\",\"SyntaxError\",\"RangeError\",\"URIError\",\"EvalError\",\"AggregateError\"]),b=(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},h=(e,t,i=[])=>{let r=Date.now();r-w>=6e4&&(w=r,m=0,f.clear());let a=`${e}:${t.slice(0,2e3)}`,x=f.get(a);if(x!==void 0&&r-x<1e3||m>=20){g++;return}f.set(a,r),m++,i.push({key:\"executor.ui.failure.suppressed\",value:{intValue:String(g)}}),g=0;let E=Array.from(crypto.getRandomValues(new Uint8Array(16)),s=>s.toString(16).padStart(2,\"0\")).join(\"\"),S=`${Date.now()}000000`,n,l=\"Sending error report\\u2026\",k=()=>{if(d?.open)return;let s=document.createElement(\"div\"),D=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 R=document.createElement(\"details\"),T=document.createElement(\"summary\");T.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: ${E}`,R.append(T,c),n=document.createElement(\"p\"),n.setAttribute(\"role\",\"status\"),n.textContent=l;let u=document.createElement(\"button\");u.type=\"button\",u.textContent=\"Reload page\",u.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,R,n,u,p),D.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:E,spanId:E.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=>{l=s.ok?\"Error report sent.\":\"Could not send the error report. You can copy the error details.\",n&&(n.textContent=l)},()=>{l=\"Could not send the error report. You can copy the error details.\",n&&(n.textContent=l)})};window.addEventListener(\"error\",e=>{if(e instanceof ErrorEvent){if(v.test(e.filename)||e.error===null&&e.lineno===0&&A.has(e.message))return;let t=b(e.filename,e.lineno,e.colno);e.error instanceof Error&&V.has(e.error.name)&&t.push({key:\"exception.type\",value:{stringValue:e.error.name}}),h(\"runtime\",e.error instanceof Error?e.error.stack??e.message:e.message,t)}else e.target instanceof HTMLScriptElement&&h(\"script\",`Could not load script: ${e.target.src}`,b(e.target.src))},!0),window.addEventListener(\"unhandledrejection\",e=>{let t=e.reason;h(\"rejection\",t instanceof Error?t.stack??t.message:\"An app operation failed without handling its error.\")})};M();})();</script>";

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

@@ -1,16 +1,35 @@
-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 { Effect, Option, Stream } from "effect";
+import { HttpServerRequest, HttpServerResponse } from "effect/http";
+import { UiFailed, UiForbidden, type AppUiAsset, type AppUiRange, type AppUiStoredFile, type UiAccountNotice } from "../contracts/ui.js";
+/**
+ * Render an authorized version with a host-owned version 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 version: string;
+    /** The account IDs the page runs with, by requirement. */
+    readonly accountIds?: Readonly<Record<string, readonly string[]>> | 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.
- * HTML remains an uncached host-rendered entry point.
+}) => Effect.Effect<HttpServerResponse.HttpServerResponse, UiFailed | UiForbidden | E, HttpServerRequest.HttpServerRequest | R>;
+/**
+ * A version's public file, read from the host's store. The version lists it, so bytes that
+ * are gone are a storage fault, never a missing page.
+ */
+export declare const storedAppFile: <E1, E2>(stored: {
+    readonly contentType: string;
+    readonly size: number;
+    readonly etag: string;
+}, read: (range: AppUiRange | undefined) => Effect.Effect<Option.Option<{
+    readonly body: Stream.Stream<Uint8Array, E1>;
+}>, E2>) => AppUiStoredFile;
+/** The file a URL path names: each segment percent-decoded, or none when one does not decode. */
+export declare const assetPath: (path: string) => Option.Option<string>;
+/** Serve an asset only after the host has checked current access and file existence.
+ * Asset URLs name their version, 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; other HTML files are served as they are.
  */
-export declare const appAsset: (asset: AppUiAsset | undefined, build: string, path: string) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, HttpServerRequest.HttpServerRequest>;
+export declare const appAsset: (asset: AppUiAsset | undefined, build: string, path: string) => Effect.Effect<HttpServerResponse.HttpServerResponse, UiFailed, 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 c=()=>{let s=document.getElementById(\"executor-context\")?.textContent;if(!s)return;let n=JSON.parse(s);if(typeof n!=\"object\"||n===null||!(\"version\"in n))return;let r=n.version;if(typeof r!=\"string\"||r.length===0)return;let t=new EventSource(\"/_executor/version\"),d=!1,o=()=>{d||(d=!0,t.close(),location.reload())};t.addEventListener(\"version\",i=>{let e=JSON.parse(i.data);typeof e==\"object\"&&e!==null&&\"version\"in e&&(e.version===null||typeof e.version==\"string\")&&e.version!==r&&o()}),t.addEventListener(\"revoked\",o),window.addEventListener(\"executor:deployment-changed\",o),window.addEventListener(\"pagehide\",()=>t.close(),{once:!0}),window.addEventListener(\"pageshow\",i=>{i.persisted&&o()})};c();})();";

package/types/apps/src/implementation/upstream-error.d.ts

@@ -0,0 +1,7 @@
+import { UpstreamError } from "../contracts/failure.js";
+/** Whether `bounded` shortened this message, so it may end partway through a secret. */
+export declare const isShortenedUpstream: (message: string) => boolean;
+/** The error a JSON error body states, if it uses a nested error object or OAuth's format. */
+export declare const bodyUpstreamError: (json: unknown) => UpstreamError | undefined;
+/** The `error` and `error_description` of a Bearer challenge (RFC 6750, section 3). */
+export declare const challengeUpstreamError: (header: string | undefined) => UpstreamError | undefined;

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

@@ -1,13 +1,21 @@
 /** Native webhook dispatch. The author verifies signatures before parsing or performing side effects. */
 import { Effect, Schema } from "effect";
-import type { AppDefinition } from "../contracts/app.js";
-import { HostDeclarationInvalid, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, type ResolvedAccounts } from "../contracts/host.js";
+import type { AppDefinition, ScopedSlots } from "../contracts/app.js";
+import { HostDeclarationInvalid, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostAccountsInvalid, HostOutputInvalid } from "../contracts/host.js";
 import { type WebhookCommand } from "../contracts/webhook-protocol.js";
-/** Run one hook with freshly bound context. No credentials or raw failures enter the response envelope. */
+type ScopeAccounts = {
+    readonly accounts: Readonly<Record<string, unknown>>;
+};
+/**
+ * Run one hook with freshly bound context. No credentials or raw failures enter the response
+ * envelope. An app-account hook runs without a caller: its context has no `user`, whatever the
+ * invocation bound.
+ */
 export declare const dispatchWebhook: <Context extends {
     readonly signal?: AbortSignal;
-    readonly accounts: Readonly<Record<string, unknown>>;
-}>(definition: AppDefinition<Context>, command: WebhookCommand, context: Context, accounts: ResolvedAccounts) => Effect.Effect<Schema.Json | {
+    readonly app: ScopeAccounts;
+    readonly user?: ScopeAccounts;
+}>(definition: AppDefinition<Context>, command: WebhookCommand, context: Context, slots: ScopedSlots) => Effect.Effect<Schema.Json | {
     readonly name: string;
     readonly account: string;
     readonly configSchema: {
@@ -26,4 +34,5 @@ export declare const dispatchWebhook: <Context extends {
         readonly [x: string]: string;
     };
     readonly body: string;
-}, HostDeclarationInvalid | HostOperationNotFound | HostOperationFailed | HostInputInvalid | HostOutputInvalid, never>;
+}, HostDeclarationInvalid | HostAccountsInvalid | HostOperationNotFound | HostOperationFailed | HostInputInvalid | HostOutputInvalid, never>;
+export {};

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

@@ -1,8 +1,20 @@
 /** Author-facing step methods delegate persistence to the host's durable engine. */
 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>;
+import type { AccountScope, AppDefinition } from "../contracts/app.js";
+import type { AppRequirements } from "../contracts/context.js";
+import { WorkflowFailure, type WorkflowContext, type WorkflowExecution, type WorkflowStepContext as AuthorStepContext } from "../contracts/workflows.js";
+/** A step's context as the host builds it: a run without a caller has no `user`. */
+type WorkflowStepContext = AuthorStepContext<AppRequirements, AccountScope> & Partial<Pick<AuthorStepContext, "user">>;
+/**
+ * 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>;
+export {};

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

@@ -1,23 +1,30 @@
 /** Ordinary async workflow declarations, adapted once into native Effect handlers. */
-import { type Schema as EffectSchema } from "effect";
+import type { Schema as EffectSchema } from "effect";
 import type { AppWorkflow, WorkflowContext } from "../contracts/workflows.js";
+import type { AppRequirements } from "../contracts/context.js";
+import type { AccountScope } from "../contracts/app.js";
 import { type Schema } from "./schema.js";
 declare const NativeWorkflow: unique symbol;
+/**
+ * The context any workflow may declare: either scope, so a run started without a caller, such as
+ * by an app schedule, declares `WorkflowContext<typeof requirements, "app">`.
+ */
+export type AnyWorkflowContext = WorkflowContext<AppRequirements, AccountScope>;
 declare const HandlerContext: unique symbol;
 /** A workflow declaration retains input/output inference and required context compatibility. */
-export interface Workflow<Input, Output, Context extends WorkflowContext = WorkflowContext> {
+export interface Workflow<Input, Output, Context extends AnyWorkflowContext = WorkflowContext> {
     readonly [HandlerContext]?: (context: Context) => void;
     readonly [NativeWorkflow]: AppWorkflow<Input, Output>;
 }
 /** Composition view erases input only after retaining its runtime decoder. */
-export interface WorkflowDeclaration<Context extends WorkflowContext> {
+export interface WorkflowDeclaration<Context extends AnyWorkflowContext> {
     readonly [HandlerContext]?: (context: Context) => void;
     readonly [NativeWorkflow]: Omit<AppWorkflow<never>, "input"> & {
         readonly input: EffectSchema.Decoder<unknown>;
     };
 }
 /** Declare durable orchestration without starting a run or performing I/O. */
-export declare const workflow: <Input, Output, Context extends WorkflowContext = WorkflowContext>(options: {
+export declare const workflow: <Input, Output, Context extends AnyWorkflowContext = WorkflowContext>(options: {
     readonly input: Schema<Input, boolean>;
     readonly output?: Schema<Output, boolean>;
     readonly description?: string;

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

@@ -1,4 +1,5 @@
 export { ProviderError } from "./contracts/provider-error.js";
+export { FetchOptionUnsupported, NetworkRefused } from "./contracts/network.js";
 export type { AppCache, CacheLoadContext, CacheGetOptions } from "./contracts/cache.js";
 export { CacheError } from "../../app-cache/src/contracts/cache.js";
 /**
@@ -6,48 +7,92 @@ export { CacheError } from "../../app-cache/src/contracts/cache.js";
  * exposes ordinary declarations, schema helpers and Promise operations.
  */
 import { type Schema as EffectSchema } from "effect";
-import type { WebhookContext } from "./contracts/context.js";
+import type { AppRequirements, WebhookContext } from "./contracts/context.js";
+import type { AccountScope } from "./contracts/app.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";
-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";
+import { type PlacementInput, type RequestPlacements } from "./implementation/placement.js";
+import type { Placement } from "./contracts/placement.js";
+import type { QueryContext as NativeQueryContext } from "./contracts/context.js";
+import { query as operationQuery, type AnyContext, type OperationOptions } from "./implementation/operations.js";
+import { type Fields, type Infer, type ObjectSchema, type Schema, type SecretFields, type SecretObject } from "./implementation/schema.js";
+export { DeclarationInvalid, type DeclarationIssue, 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, 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 { base64, basic, bearer, header, t, type FieldRef, type FieldRefs, type PlacementInput, type PlacementValue, type RequestPlacements, } from "./implementation/placement.js";
+export type { Placement };
+export type { AccountRequest } from "./contracts/provider.js";
+export { accountRouter } from "./implementation/account-router.js";
+export { router, dynamicRouter, withApprovals, renameTools, type OperationChild, type OperationDeclaration, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
+export type { RouterIcon } from "./contracts/router.js";
+export type { AppIcon } from "./contracts/icons.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>>>;
+/** The names of an object schema's fields, which a method's `request` can reference. */
+type FieldNameOf<S> = S extends ObjectSchema<infer F> ? keyof F & string : never;
 /** Default OAuth fields visible to app code. Host-only grants and clients stay private. */
 export declare const OAuth2AccessToken: Schema<{
     readonly access_token: string;
 }, false>;
-/** Declare a secrets method without requiring an Effect schema from the author. */
+/**
+ * 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. `request` says
+ * where its secret fields may be sent, such as `({ token }) => bearer(token)`; it runs once, here.
+ */
 export declare const secrets: <const F extends Fields>(options: {
     readonly label: string;
     readonly fields: ObjectSchema<F>;
+    readonly request?: RequestPlacements<keyof F & string>;
 }) => SecretsMethod<ObjectSchema<F>>;
-/** Declare OAuth discovery/endpoints and an optional app-visible response projection. */
-export declare function oauth2(options: OAuth2Config): OAuth2Method<typeof OAuth2AccessToken>;
+/**
+ * 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.
+ * `request` says where the projected secret fields may be sent, such as
+ * `({ access_token }) => bearer(access_token)`; it runs once, here.
+ */
+export declare function oauth2(options: OAuth2Config & {
+    readonly request?: RequestPlacements<"access_token">;
+}): OAuth2Method<typeof OAuth2AccessToken>;
 export declare function oauth2<Response extends Schema<unknown, boolean>>(options: OAuth2Config & {
     readonly response: Response;
+    readonly request?: RequestPlacements<FieldNameOf<Response>>;
 }): OAuth2Method<Response>;
-export type { AccountSlots } from "./contracts/app.js";
-export type { AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext, } from "./contracts/context.js";
+export type { AccountScope, AccountSlots, WebhookAccount } from "./contracts/app.js";
+export type { AnyScopeMutationContext, AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext, } from "./contracts/context.js";
 export { type App, type AppDefinition, defineApp } from "./implementation/app.js";
+export { event, type EventDeclaration, type EventEmitter } from "./implementation/events.js";
+export type { EmitOptions } from "./contracts/events.js";
 export type { Approval, ApprovalContext, ApprovalDecision } from "./approval.js";
 type AuthorWebhook<Member, Config, State> = Member extends object ? Omit<PromiseMethods<Member>, "config" | "state"> & {
     readonly config: Config;
     readonly state: State;
 } : never;
 /** Author lifecycle methods use async functions and share native decoded context/state types. */
-export type Webhook<Context extends WebhookContext, Config extends Schema<unknown, boolean>, State extends Schema<unknown, boolean>> = AuthorWebhook<NativeWebhook<Context, EffectSchema.Decoder<Infer<Config>>, EffectSchema.Decoder<Infer<State>>>, Config, State>;
+/**
+ * A webhook's context names its source account's scope: one with `user` serves a user requirement
+ * (`account: { user: "x" }`), one of the `"app"` scope an app requirement (`account: { app: "x" }`)
+ * and runs without a caller.
+ */
+export type Webhook<Context extends WebhookContext<AppRequirements, AccountScope>, Config extends Schema<unknown, boolean>, State extends Schema<unknown, boolean>> = AuthorWebhook<NativeWebhook<Context, EffectSchema.Decoder<Infer<Config>>, EffectSchema.Decoder<Infer<State>>>, Config, State>;
 export { ResponseDecodeError, ResponseStatusError } from "./contracts/http.js";
 /** Native fetch-compatible response accepted at the author boundary. */
 export type JsonResponse = PromiseMethods<NativeResponse>;
@@ -55,11 +100,16 @@ export type JsonResponse = PromiseMethods<NativeResponse>;
 export declare const decodeJson: <T>(response: JsonResponse, schema: Schema<T, boolean>) => Promise<T>;
 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 type { Sql, SqlCursor, SqlReader, SqlRow, SqlTransaction, SqlValue, } from "./contracts/sql.js";
+/**
+ * `query(options, run)` declares a read operation. `query(name, value)` inside a method's
+ * `request` places a credential in a query parameter, such as `query("key", key)`.
+ */
+export declare function query(name: string, value: PlacementInput): Placement;
+export declare function query<Input, Output, Context extends AnyContext = NativeQueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>): ReturnType<typeof operationQuery<Input, Output, Context>>;
+export { mutation, withApproval, toolAnnotations, type Approved, 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";
-export { interval, cron, type ScheduleDeclaration } from "./implementation/schedules.js";
+export { appCron, appInterval, userCron, userInterval, type ScheduleDeclaration, } from "./implementation/schedules.js";
 export type { AppSkillSource as Skill, SkillFile } from "./contracts/skills.js";

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

@@ -1,10 +1,30 @@
 /** HTTP MCP helpers. Requires the optional @modelcontextprotocol/sdk peer. */
 import type { OperationKinds } from "./implementation/protocol-operations.js";
+import type { McpHealthOptions } from "./contracts/mcp.js";
+import type { AccountCheckContext, AuthMethods } from "./contracts/provider.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;
-}>;
+export { McpCredentialsUnverified, McpError, type McpHealthOptions, type McpToolContext, type McpToolsOptions, type McpToolResult, } from "./contracts/mcp.js";
+/**
+ * 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>>;
+/**
+ * A provider `health` check for an MCP server. Pass the check context `health` receives, then the
+ * server's `url` and the `headers` that send the account's credentials:
+ * `health: (check) => mcpHealth(check, { url, headers: headers(check.account) })`.
+ *
+ * It connects with those headers, initializes, and reads the first page of tools, then does the
+ * same without any headers. No tool runs. The check passes only when the server accepts the account
+ * and refuses the attempt without credentials. A refused account throws `ProviderError`, as HTTP
+ * helpers do. An unreachable or unusable server throws `McpError`, and a request Executor's network
+ * refuses throws `NetworkRefused`. A server that also answers without credentials, or whose answer
+ * to that attempt is not a refusal, throws `McpCredentialsUnverified`. Each of these errors means
+ * the check could not verify the account, and the account form explains why. Send credentials only
+ * in `headers`; the attempt without them uses the same `url`. The check context's `signal` cancels
+ * both attempts, and they share one budget that ends early enough before its `deadline` to report a
+ * server that did not answer in time. `timeoutMs` can only shorten that budget.
+ */
+export declare const mcpHealth: <Auth extends AuthMethods>(check: AccountCheckContext<Auth>, options: McpHealthOptions) => Promise<void>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";

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

@@ -2,11 +2,16 @@
 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";
+/**
+ * The names `liveOpenapiRouter` gives a document's operations, from each operation's
+ * operationId, first tag, method and path alone. It reads no document and compiles nothing.
+ */
+export { planOperationNames, type OperationNameInput } from "./implementation/openapi-names.js";
+export { liveOpenapiRouter, openapiToolNames, type OpenapiSourceOptions, type OpenapiToolNamesOptions, } from "./implementation/openapi-source.js";

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

@@ -1,4 +1,4 @@
-import { AsyncResult, type Atom } from "effect/unstable/reactivity";
+import { AsyncResult, type Atom } from "effect/reactivity";
 /** Subscribe for the component lifetime. Each mount owns and disposes its registry, including StrictMode remounts. */
 export declare const useAppQuery: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => {
     data: A | undefined;