apps 0.0.1-beta.5 → 0.0.1-beta.55

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

@@ -1,35 +1,28 @@
 /** Remote skill readers return complete portable bundles, never installed host files. */
 import { Effect } from "effect";
-import { SkillLoadFailed, type GitHubSkillsOptions, type WellKnownSkillsOptions, type SkillTransport } from "../contracts/skills.js";
+import { NetworkRefused } from "../contracts/network.js";
+import { ProviderError } from "../contracts/provider-error.js";
+import { AppSkills, SkillLoadFailed, type GitHubSkillsOptions, type WellKnownSkillsOptions, type SkillTransport } from "../contracts/skills.js";
 /** Give every failure without a message one that names the service. */
-export declare const withService: (service: string | undefined) => <A, R>(effect: Effect.Effect<A, SkillLoadFailed, R>) => Effect.Effect<A, SkillLoadFailed, R>;
+export declare const withService: (service: string | undefined) => <A, R>(effect: Effect.Effect<A, SkillLoadFailed | NetworkRefused, R>) => Effect.Effect<A, NetworkRefused | SkillLoadFailed, R>;
+interface ReadRequest {
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Describe a refusal by Executor's app network; defaults to the refusal itself. */
+    readonly refused?: (refused: NetworkRefused) => SkillLoadFailed | NetworkRefused;
+}
 /** One loader invocation owns its byte budget and all of its network requests. */
 export declare const reader: (transport: SkillTransport) => Effect.Effect<{
-    fetchBytes: (url: string, post?: {
-        readonly body: Uint8Array;
-        readonly headers: Record<string, string>;
-    }) => Effect.Effect<Uint8Array<ArrayBuffer>, SkillLoadFailed, never>;
-    read: (url: string) => Effect.Effect<string, SkillLoadFailed, never>;
-    json: (url: string) => Effect.Effect<unknown, SkillLoadFailed, never>;
+    fetchBytes: (url: string, request?: ReadRequest & {
+        readonly body?: Uint8Array;
+    }) => Effect.Effect<Uint8Array<ArrayBuffer>, NetworkRefused | SkillLoadFailed, never>;
+    read: (url: string, request?: ReadRequest) => Effect.Effect<string, NetworkRefused | SkillLoadFailed, never>;
+    json: (url: string) => Effect.Effect<unknown, NetworkRefused | SkillLoadFailed, never>;
 }, never, never>;
-export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<readonly {
-    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;
-}[], SkillLoadFailed, never>;
+export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<typeof AppSkills.Type, SkillLoadFailed | NetworkRefused | ProviderError>;
 /** Fetch all indexed files and reject a publication whose index changes during the read. */
 export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) => Effect.Effect<readonly {
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;
@@ -40,4 +33,5 @@ export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) =>
         readonly [x: string]: string;
     };
     readonly "allowed-tools"?: string;
-}[], SkillLoadFailed, never>;
+}[], NetworkRefused | SkillLoadFailed, never>;
+export {};

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

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

@@ -1,4 +1,4 @@
-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. */
@@ -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 deployment'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 deploymentDocument: (html: string, deployment: 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 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 { HttpServerRequest, HttpServerResponse } from "effect/http";
+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/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 JSON-RPC's or OAuth's error 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

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

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

@@ -8,7 +8,7 @@ import { WorkflowFailure, type WorkflowContext, type WorkflowExecution, type Wor
  */
 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">, 
+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;

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

@@ -1,5 +1,5 @@
 /** 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 Schema } from "./schema.js";
 declare const NativeWorkflow: unique symbol;

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";
 /**
@@ -8,32 +9,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 OperationChild, type OperationDeclaration, 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;
@@ -41,6 +59,8 @@ export declare function oauth2<Response extends Schema<unknown, boolean>>(option
 export type { AccountSlots } from "./contracts/app.js";
 export type { 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;
@@ -55,9 +75,8 @@ 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";
+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

@@ -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,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/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;

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

@@ -1,12 +1,13 @@
 import { type FolderSkillsOptions, type GitHubSkillsOptions, type SkillReaderOptions, type WellKnownSkillsOptions, type SkillFile } from "./contracts/skills.js";
-export { SkillLoadFailed, SkillDefinitionInvalid, SkillServiceName, type SkillReaderOptions, type FolderSkillsOptions, type AppSkillSource as Skill, type SkillFile, type GitHubSkillsOptions, type SkillCacheOptions, type WellKnownSkillsOptions, } from "./contracts/skills.js";
+export { SkillLoadFailed, SkillDefinitionInvalid, SkillServiceName, type SkillReaderOptions, type FolderSkillsOptions, type AppSkillSource as Skill, type SkillFile, type GitHubSkillsAccount, type GitHubSkillsOptions, type SkillCacheOptions, type WellKnownSkillsOptions, } from "./contracts/skills.js";
 /**
- * Fetch a public GitHub skill collection from one resolved commit. Pass `cache: ctx.cache` to reuse
- * the catalog; without it, mutable refs resolve again on each call.
+ * Fetch a GitHub skill collection from one resolved commit. A private repository takes `account`
+ * and its `token`. Pass `cache: ctx.cache` to reuse the catalog; without it, mutable refs resolve
+ * again on each call.
  */
 export declare const githubSkills: (options: GitHubSkillsOptions) => Promise<readonly {
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;
@@ -20,8 +21,8 @@ export declare const githubSkills: (options: GitHubSkillsOptions) => Promise<rea
 }[]>;
 /** Fetch a published skill index and its text files. Pass `cache: ctx.cache` to reuse the catalog. */
 export declare const wellKnownSkills: (options: WellKnownSkillsOptions) => Promise<readonly {
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;
@@ -35,8 +36,8 @@ export declare const wellKnownSkills: (options: WellKnownSkillsOptions) => Promi
 }[]>;
 /** Parse a bundled standard skill directory into an app capability. */
 export declare const fileSkill: (files: readonly SkillFile[]) => Promise<{
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;
@@ -50,8 +51,8 @@ export declare const fileSkill: (files: readonly SkillFile[]) => Promise<{
 }>;
 /** Read skill directories from ctx.files. Omitted path selects skills/; missing folders return []. */
 export declare const folderSkills: (options: FolderSkillsOptions) => Promise<readonly {
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;
@@ -65,7 +66,8 @@ export declare const folderSkills: (options: FolderSkillsOptions) => Promise<rea
 }[]>;
 /**
  * Read files for a custom remote skill loader, such as one for GitLab. Reads share one byte
- * budget and reject with the same safe SkillLoadFailed errors as githubSkills, naming `service`.
+ * budget and reject with the same safe SkillLoadFailed errors as githubSkills, naming `service`,
+ * or with `NetworkRefused` when Executor's network refuses a request.
  */
 export declare const skillReader: (options: SkillReaderOptions) => {
     /** Fetch one UTF-8 text file. */

package/types/telemetry/src/app-records.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What the host keeps of the spans and logs an app isolate returns.
+ *
+ * Those records come from whatever framework the app's build bundles, and the app's own code runs
+ * in the same isolate: it can throw any text, name its errors and codes, and rewrite every record
+ * before the isolate returns it. So the host does not filter the records it receives. It builds
+ * new ones from a closed vocabulary: the framework's span names, attributes whose values are
+ * closed sets, counts and status codes, and each exception's kind. Ids, parents and timings are
+ * kept. Everything else, including events other than exceptions, links, status and exception
+ * messages, stacks and log bodies, is dropped or replaced with a fixed sentence.
+ *
+ * The vocabulary is the framework's (`packages/apps`, `app-cache`, `app-data`): host request
+ * operations, failure sources and reasons, MCP and cache attributes. A name or value outside it is
+ * recorded as `unrecognized` or not at all. `bun run check` (`scripts/check-app-telemetry.ts`)
+ * fails when the framework names a span or sets an attribute key this vocabulary does not know.
+ */
+import type { Schema } from "effect";
+type Json = Schema.Json;
+type JsonObject = {
+    readonly [key: string]: Json;
+};
+/** What an exception message, stack or log body from an app isolate records instead. */
+export declare const appText = "Text from the app is not recorded";
+/** The framework's span names, and the libraries' spans it runs. */
+export declare const appSpanNames: ReadonlySet<string>;
+export declare const appSpanAttributeKeys: ReadonlySet<string>;
+/**
+ * Attributes the framework sets whose values the app chooses, such as its tool names, so the host
+ * drops them. `scripts/check-app-telemetry.ts` fails on a framework attribute in neither set.
+ */
+export declare const droppedAppAttributeKeys: ReadonlySet<string>;
+/** The span the host records for one an app isolate returned, or nothing without its timings. */
+export declare const appSpan: (span: JsonObject & {
+    readonly traceId: string;
+    readonly spanId: string;
+}) => JsonObject | undefined;
+/** The log record the host records for one an app isolate returned. */
+export declare const appLog: (log: JsonObject & {
+    readonly traceId?: string | undefined;
+    readonly spanId?: string | undefined;
+}) => JsonObject;
+export {};

package/types/telemetry/src/browser-operations.d.ts

@@ -1,11 +1,14 @@
 /** Correlate transport and decoded outcomes without exporting response bodies or errors. */
 import { Effect, Schema, Tracer } from "effect";
-import { HttpClient, HttpClientError } from "effect/unstable/http";
-/** A random document identity. It is never an authentication or user identifier. */
-export declare const browserPageId: () => string;
+import { HttpClient, HttpClientError } from "effect/http";
+/**
+ * A random identity for the current browser document. It is never an authentication or user
+ * identifier. Server renders have no document, so they get none instead of sharing one per isolate.
+ */
+export declare const browserPageId: () => string | undefined;
 /** Safe event shared with the host's error reporter and product analytics. */
 export declare const BrowserOperationFailure: Schema.Struct<{
-    readonly error_type: Schema.Literals<readonly ["BrowserDecodeFailed", "BrowserTransportFailed", "BrowserOperationFailed"]>;
+    readonly error_type: Schema.Literals<readonly ["BrowserDecodeFailed", "BrowserConnectionFailed", "BrowserTransportFailed", "BrowserOperationFailed"]>;
     readonly trace_id: Schema.String;
     readonly span_id: Schema.String;
     readonly page_id: Schema.String;

package/types/telemetry/src/browser.d.ts

@@ -1,11 +1,16 @@
 /** Browser-owned Effect telemetry, shared by Promise calls and Atom runtimes. */
 import { Context, Effect, Layer, ManagedRuntime } from "effect";
-import { OtlpExporter } from "effect/unstable/observability";
-import { Atom } from "effect/unstable/reactivity";
+import { OtlpExporter } from "effect/observability";
+import { Atom } from "effect/reactivity";
 import type { TelemetryConfig } from "./config.js";
 declare const BrowserTelemetry_base: Context.ServiceClass<BrowserTelemetry, "executor/BrowserTelemetry", {
+    /**
+     * `load` names the document's initial route without a span: hydration resolves no route
+     * change, and first load is measured by the vitals. `start` opens a `ui.navigation` span
+     * that the router's next `end` closes or the next `start` interrupts.
+     */
     readonly navigation: (event: {
-        readonly type: "start";
+        readonly type: "load" | "start";
         readonly path: string;
     } | {
         readonly type: "end";

package/types/telemetry/src/config.d.ts

@@ -33,8 +33,8 @@ export declare const TelemetryConfig: Schema.Struct<{
 export type TelemetryConfig = typeof TelemetryConfig.Type;
 /** Host-only destinations; never copied into an app's invocation telemetry capability. */
 export declare const CurrentTelemetryConfig: Context.Reference<{
-    readonly version: string;
     readonly service: string;
+    readonly version: string;
     readonly environment: string;
     readonly clock?: "system" | "cloudflare-io" | undefined;
     readonly traces?: {
@@ -59,8 +59,8 @@ export declare const CurrentTelemetryConfig: Context.Reference<{
 } | undefined>;
 /** Read OTLP endpoints uniformly for all signals; development chooses which signals to configure. */
 export declare const telemetryConfig: (service: string) => Effect.Effect<{
-    readonly version: string;
     readonly service: string;
+    readonly version: string;
     readonly environment: string;
     readonly clock?: "system" | "cloudflare-io" | undefined;
     readonly traces?: {

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

@@ -5,5 +5,6 @@ export { captureTelemetry, traceHeaders, withRemoteSpan, invocationFetch, type I
 export { collectTelemetry, forwardTelemetry, makeTelemetryForwarder, TelemetryBatch, } from "./relay.js";
 export { TraceContext, currentTraceContext, externalTrace, traceLinks } from "./trace-context.js";
 export { pendingSpan } from "./pending-span.js";
+export { makeOwnershipAccounting, measuredSpan, owned, ownedBy, ownerAttribute, type Owner, type SpanMeasure, } from "./ownership.js";
 export { recordWorkerMeasurements } from "./measurements.js";
 export { allowlistedSpans, httpSpanAttributeAllowlist, spanAttributeAllowed, } from "./span-attributes.js";

package/types/telemetry/src/layer.d.ts

@@ -2,6 +2,6 @@
 import { Layer, Logger } from "effect";
 import { type TelemetryConfig } from "./config.js";
 /** Build one tracer per runtime. Event mode defers export until Worker scope finalization. */
-export declare const telemetryLayer: (config: TelemetryConfig, lifetime?: "process" | "event", logger?: Logger.Logger<unknown, void>) => Layer.Layer<import("effect/unstable/observability/OtlpExporter").Flusher, never, never>;
+export declare const telemetryLayer: (config: TelemetryConfig, lifetime?: "process" | "event", logger?: Logger.Logger<unknown, void>) => Layer.Layer<import("effect/observability/OtlpExporter").Flusher, never, never>;
 /** Node/local entry points resolve telemetry once and share it for their process lifetime. */
-export declare const telemetryFromConfig: (service: string) => Layer.Layer<import("effect/unstable/observability/OtlpExporter").Flusher, import("effect/Schema").SchemaError | import("effect/Config").ConfigError, never>;
+export declare const telemetryFromConfig: (service: string) => Layer.Layer<import("effect/observability/OtlpExporter").Flusher, import("effect/Schema").SchemaError | import("effect/Config").ConfigError, never>;