apps 0.0.1-beta.8 → 0.0.1-beta.81

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

@@ -1,17 +1,51 @@
 /** Browser-to-host operations bind identity and authentication outside authored app code. */
-import { Schema } from "effect";
-import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/unstable/httpapi";
+import { Schema, type Effect, type Stream } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api";
 /** Non-secret page context injected by the serving host. */
 export declare const UiContext: Schema.Struct<{
     readonly deployment: Schema.NonEmptyString;
     readonly profile: Schema.optional<Schema.NonEmptyString>;
     readonly expectedProfileRevision: Schema.optional<Schema.Int>;
 }>;
+/** A problem with one of the page profile's accounts, from stored state. Labels are the owner's own names. */
+export type UiAccountProblem = {
+    readonly provider: string;
+    readonly reason: "missing" | "removed" | "incompatible";
+} | {
+    readonly provider: string;
+    readonly account: string;
+    readonly reason: "credentials_rejected" | "forbidden" | "upstream_unavailable" | "check_failed";
+};
+/** Account problems found when the page opened, with dashboard links that resolve them. */
+export interface UiAccountNotice {
+    readonly app: string;
+    readonly problems: readonly UiAccountProblem[];
+    /** The profile's accounts in the dashboard. */
+    readonly fix: string;
+    /** The dashboard chooser, returning to this page. */
+    readonly choose: string;
+}
 /** Retained browser bytes. Hosts authorize access before reading or rendering them. */
-export interface AppUiAsset {
+export interface AppUiFile {
     readonly body: Uint8Array;
     readonly contentType: string;
 }
+/** One byte range of a stored file, already within its size. */
+export interface AppUiRange {
+    readonly offset: number;
+    readonly length: number;
+}
+/**
+ * A public file the deployment's source served from `ui/public/`, which the host copied to its
+ * own store. `etag` names its exact bytes. Hosts authorize access before reading it.
+ */
+export interface AppUiStoredFile {
+    readonly contentType: string;
+    readonly size: number;
+    readonly etag: string;
+    readonly read: (range: AppUiRange | undefined) => Effect.Effect<Stream.Stream<Uint8Array, UiFailed>, UiFailed>;
+}
+export type AppUiAsset = AppUiFile | AppUiStoredFile;
 /** Requests name an operation on this app and the page's deployment, never another app or account. */
 export declare const UiOperation: Schema.Struct<{
     readonly name: Schema.NonEmptyString;

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

@@ -1,5 +1,6 @@
 /** Portable workflow declarations, run views and durable execution capabilities. */
 import { Schema, type Effect } from "effect";
+import { RecordedMessage } from "../../../utils/src/recorded-message.js";
 import { JsonValue } from "./schema.js";
 import type { AppContext, AppRequirements, QueryContext, MutationContext } from "./context.js";
 import type { Operation } from "../implementation/operations.js";
@@ -49,6 +50,11 @@ declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedS
 }>, import("effect/Cause").YieldableError>;
 /** Failures cross host boundaries as reason codes plus the app's own bounded error detail. */
 export declare class WorkflowFailure extends WorkflowFailure_base {
+    /**
+     * The step name and error detail are the app's. Its run's owner reads them; telemetry records
+     * only the reason, however the failure was built or decoded.
+     */
+    get [RecordedMessage](): string | undefined;
 }
 /** Explicitly stop retrying an authored step. Its message is reported like any step error. */
 export declare class NonRetryableError extends Error {

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

@@ -1,5 +1,4 @@
-/** Native workerd SQLite capability; used only by the generated data facet, never browser bundles. */
-import * as Sqlite from "@effect/sql-sqlite-do/SqliteClient";
-import type { AppStorage } from "./contracts/storage.js";
-/** Bind one facet's raw storage at the runtime edge. Each operation owns its native SQL scope. */
-export declare const facetStorage: (storage: NonNullable<Sqlite.SqliteClientConfig["storage"]>) => AppStorage;
+/** The data facet's storage capability; used only by the generated data facet, never browser bundles. */
+import type { AppSqlStorage } from "./contracts/sql.js";
+/** Bind one facet's storage at the runtime edge. App code receives `ctx.sql` over it, never the storage. */
+export declare const facetStorage: (storage: AppSqlStorage) => AppSqlStorage;

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

@@ -6,6 +6,11 @@ export { isolatedCacheSession } from "./implementation/cache-session.js";
 export declare const hostContext: (accounts: ResolvedAccountsInput, approval?: unknown) => HostContext;
 /** Portable Promise handler. Invoke only after the host has authorized and resolved accounts. */
 export declare const createAppHandler: (app: unknown) => ((request: Request, context: HostContext) => Promise<Response>);
+/**
+ * The clock this framework's spans read, in nanoseconds. The runtime's bridge times the isolate's
+ * whole dispatch with it, so that time and the invocation's own timing share one clock.
+ */
+export declare const isolatedClock: () => bigint;
 /** Isolates return bounded, telemetry beside the protocol result; no exporter secret enters app code. */
 export declare const createIsolatedAppHandler: (app: unknown) => (request: Request, context: HostContext) => Promise<Response>;
 /**

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

@@ -3,10 +3,11 @@ import { type RouterDeclaration } from "./router.js";
  * Discover each selected account's router and combine matching names.
  * Calls take { accountId, input }; each branch retains its account's input schema,
  * credentials, approval and output validation. Empty selections expose no operations.
- * Discovery is sequential and cancellation follows the caller's signal.
+ * Discovery is sequential and cancellation follows the caller's signal. `discover` may return the
+ * router or a Promise of it, and the combined router keeps its operations' handler contexts.
  */
 export declare const accountRouter: <Account extends {
     readonly id: string;
-}>(accounts: readonly Account[], discover: (account: Account) => Promise<RouterDeclaration>, options: {
+}, Query = unknown, Mutation = unknown>(accounts: readonly Account[], discover: (account: Account) => RouterDeclaration<Query, Mutation> | Promise<RouterDeclaration<Query, Mutation>>, options: {
     readonly signal: AbortSignal;
-}) => Promise<RouterDeclaration>;
+}) => Promise<RouterDeclaration<Query, Mutation>>;

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

@@ -1,12 +1,32 @@
 /** Small, explicit adapters between authored callbacks and native Effect operations. */
-import { Effect } from "effect";
+import { Effect, type Context } from "effect";
 /** Project one Effect operation into its author-facing Promise signature. */
 export type PromiseMethod<Method> = Method extends (...args: infer Args) => Effect.Effect<infer A, infer _E> ? (...args: Args) => Promise<A> : Method;
 /** Project only an object's methods; data and schema types are not recursively rewritten. */
 export type PromiseMethods<T> = {
     readonly [Key in keyof T]: PromiseMethod<T[Key]>;
 };
-/** Reuse a framework callback's cancellation-bound Effect, or adapt an ordinary async callback. */
-export declare const fromPromise: <Args extends readonly unknown[], A>(callback: (...args: Args) => Promise<A>) => ((...args: Args) => Effect.Effect<A, unknown>);
-/** Bind cancellation once so Promise callers and native framework callers run the same operation. */
-export declare const toPromise: <Args extends readonly unknown[], A, E>(operation: (...args: Args) => Effect.Effect<A, E>, signal?: AbortSignal) => ((...args: Args) => Promise<A>);
+/** Which of the app's callbacks runs, recorded on the `app.code` span around it. */
+export type AppCode = "factory" | "router" | "approval" | "handler" | "loader" | "cache" | "webhook" | "check" | "skills" | "elicitation" | "workflow" | "step";
+/**
+ * Run `effect` as the app's own code. Its time is the app's, except for work it starts for
+ * Executor, an upstream or a person, which opens its own boundary inside.
+ */
+export declare const appCode: (code: AppCode) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, import("effect/Tracer").ParentSpan>>;
+/**
+ * Reuse a framework callback's cancellation-bound Effect, or run an ordinary async callback as the
+ * app's code. Every callback an app supplies enters the framework here, so its time is the app's.
+ */
+export declare const fromPromise: <Args extends readonly unknown[], A>(callback: (...args: Args) => Promise<A>, code: AppCode) => ((...args: Args) => Effect.Effect<A, unknown>);
+/**
+ * `target[key]`, called on `target`. A method read off its object as a bare value loses its
+ * receiver, so an app's method, such as one of its cache's, enters `fromPromise` through this.
+ */
+export declare const method: <K extends PropertyKey, T extends { readonly [P in K]: (...args: never) => unknown; }>(target: T, key: K) => T[K];
+/**
+ * Bind cancellation once so Promise callers and native framework callers run the same operation.
+ * `signalOf` is the signal, or reads it from each call's arguments, such as a loader's `context.signal`.
+ */
+export declare const toPromise: <Args extends readonly unknown[], A, E>(operation: (...args: Args) => Effect.Effect<A, E>, signalOf?: AbortSignal | ((...args: Args) => AbortSignal), 
+/** Services a Promise call runs with, such as its invocation's telemetry. */
+services?: Context.Context<never>) => ((...args: Args) => Promise<A>);

package/types/apps/src/implementation/browser-scripts.gen.d.ts

@@ -0,0 +1,6 @@
+/** Compiled from src/browser/app-watch.ts. */
+export declare const appWatchSource = "\"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();})();";
+/** Compiled from src/browser/app-failure.ts. */
+export declare const appFailureSource = "\"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();})();";
+/** Compiled from src/browser/account-notice.ts. */
+export declare const accountNoticeSource = "\"use strict\";(()=>{var g=()=>{let r=document.getElementById(\"executor-account-notice\")?.textContent;if(!r)return;let t=JSON.parse(r);if(typeof t!=\"object\"||t===null||!(\"items\"in t)||!(\"fix\"in t))return;let c=t.items,s=t.fix;if(!Array.isArray(c)||typeof s!=\"string\")return;let a=()=>{let i=document.createElement(\"div\"),x=i.attachShadow({mode:\"open\"}),d=document.createElement(\"style\");d.textContent=\"aside{position:fixed;right:16px;bottom:16px;z-index:2147483647;max-width:360px;box-sizing:border-box;padding:14px 16px;border-radius:10px;border:1px solid #fcd34d;background:#fffbeb;color:#451a03;font:14px/1.45 ui-sans-serif,system-ui,sans-serif;box-shadow:0 8px 24px rgb(0 0 0/.12)}strong{display:block;margin-bottom:4px}ul{margin:0 0 10px;padding-left:18px}div{display:flex;gap:12px;align-items:center}a{color:inherit;font-weight:600}button{margin-left:auto;font:inherit;background:none;border:0;padding:0;color:inherit;text-decoration:underline;cursor:pointer}\";let e=document.createElement(\"aside\");e.setAttribute(\"role\",\"status\"),e.setAttribute(\"aria-label\",\"Account warning\");let l=document.createElement(\"strong\");l.textContent=\"Some things might not work\";let m=document.createElement(\"ul\");for(let f of c){let p=document.createElement(\"li\");p.textContent=String(f),m.append(p)}let u=document.createElement(\"div\"),n=document.createElement(\"a\");n.href=s,n.target=\"_top\",n.textContent=\"Review accounts\";let o=document.createElement(\"button\");o.type=\"button\",o.textContent=\"Dismiss\",o.addEventListener(\"click\",()=>i.remove()),u.append(n,o),e.append(l,m,u),x.append(d,e),document.documentElement.append(i)};document.readyState===\"loading\"?document.addEventListener(\"DOMContentLoaded\",a,{once:!0}):a()};g();})();";

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

@@ -1,8 +1,35 @@
-import type { AppCache, HostCache } from "../contracts/cache.js";
+/** Bind the portable Effect cache to an app invocation's author API. */
+import { type Context } from "effect";
+import type { AppCache, CacheGetOptions, HostCache } from "../contracts/cache.js";
 import type { ResolvedAccounts } from "../contracts/host.js";
+import type { JsonValue } from "../contracts/schema.js";
+/**
+ * Framework-only: `get` that also reads other keys of the same scope in its round trip to the
+ * store. Authored code never sees it; framework helpers use it when a cache provides it.
+ */
+export declare const getWithReads: unique symbol;
+/**
+ * A `get` value, the store key it was read under, and the stored values of the other keys when
+ * the value was read from the store. The values are not decoded: the caller decodes only those it
+ * uses. A key with no value reads `undefined`.
+ */
+export interface GetWithReads<A> {
+    readonly value: A;
+    /** The entry's store key, unique to the cache's scope and the key. */
+    readonly key: string;
+    /** Undefined when the value was loaded or the store did not read them: read them separately. */
+    readonly reads: readonly unknown[] | undefined;
+}
+/** The framework-only `get` an app's cache provides beside the author API. */
+export type CacheWithReads = AppCache & {
+    /** `keys` gets the entry's store key and names the other keys to read with it. */
+    readonly [getWithReads]?: <A>(options: CacheGetOptions<A>, keys: (key: string) => readonly JsonValue[]) => Promise<GetWithReads<A>>;
+};
 /** Missing host support is explicit on use; ordinary apps do not need cache support. */
 export declare const unavailableCache: HostCache;
 /** Account scopes are derived from trusted current bindings. Loaders get a fresh owned HTTP signal. */
 export declare const authorCache: (host: HostCache, accounts: ResolvedAccounts, signal: AbortSignal, 
+/** The invocation's telemetry, which Promise calls from authored code run in. */
+telemetry: Context.Context<never>, 
 /** The invocation's trusted deadline. Waiting on another caller's load never runs past it. */
 deadline?: number) => AppCache;

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

@@ -1,8 +1,8 @@
 import { Duration, Effect, Schema } from "effect";
-import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
+import type { AccountCredential, AppCache, CacheLoadContext } from "../contracts/cache.js";
 import { JsonObject, type JsonValue } from "../contracts/schema.js";
 export interface CatalogCacheOptions {
-    /** App/build scope, optionally narrowed to the current account. */
+    /** The app's cache. An account's catalog is kept in that account's scope. */
     readonly cache?: AppCache;
     /** Reuse metadata for this duration. Defaults to five minutes. */
     readonly freshFor?: Duration.Input;
@@ -11,14 +11,39 @@ export interface CatalogCacheOptions {
     /** Await a fresh revision at an explicit logical connection or refresh boundary. */
     readonly revalidate?: boolean;
 }
+/** Whose catalog a remote router reads, and the headers, such as credentials, it sends. */
+export type CatalogAccount = AccountCredential<{
+    /** Headers for this account's requests, such as its credentials. */
+    readonly headers?: Readonly<Record<string, string>>;
+}>;
+/** Why a read cannot use its account's scope. */
+export type CatalogScopeProblem = "missing-account" | "unselected-account";
+/**
+ * The cache an account's catalog lives in: the account's own scope, which token renewals keep.
+ * `credential` is what the read sends, such as headers or a token; it never enters a key. A
+ * credential without an account, or an account the app was not given, fails with `invalid`.
+ */
+export declare const catalogScope: <E>(options: {
+    readonly cache?: AppCache | undefined;
+    readonly account?: {
+        readonly id: string;
+    } | undefined;
+}, credential: unknown, invalid: (problem: CatalogScopeProblem) => E) => Effect.Effect<AppCache | undefined, E>;
 /** One load: the tools, and optionally a record describing the whole catalog. */
 export interface CatalogLoad<A> {
     readonly tools: readonly A[];
     readonly header?: JsonObject;
 }
+/** The catalog a refresh replaces, read only when its loader asks for it. */
+export interface KeptCatalog<A> {
+    readonly header: JsonObject | undefined;
+    readonly tools: Effect.Effect<readonly A[], unknown>;
+}
 export declare const catalogCache: <A extends {
     readonly name: string;
-}, S>(options: CatalogCacheOptions & {
+}, S>(options: Omit<CatalogCacheOptions, "cache"> & {
+    /** The scope from `catalogScope`; undefined keeps discovery invocation-local. */
+    readonly cache: AppCache | undefined;
     readonly prefix: readonly JsonValue[];
     readonly schema: Schema.Decoder<A>;
     /** Schema-free projection stored beside the full pages, so browsing never reads schemas. */
@@ -26,7 +51,13 @@ export declare const catalogCache: <A extends {
         readonly schema: Schema.Decoder<S>;
         readonly of: (tool: A) => S;
     };
-    readonly load: (context?: CacheLoadContext) => Effect.Effect<CatalogLoad<A>, unknown>;
+    /** Past `freshFor`, serve the kept catalog while refreshing, or refresh first. */
+    readonly stale?: "serve" | "revalidate";
+    /**
+     * Load the catalog. A refresh also gets the catalog it replaces, if one is kept, so a source
+     * that can confirm it is unchanged need not load it again.
+     */
+    readonly load: (context?: CacheLoadContext, kept?: Effect.Effect<KeptCatalog<A> | undefined, unknown>) => Effect.Effect<CatalogLoad<A>, unknown>;
 }) => Effect.Effect<{
     list: () => Effect.Effect<readonly A[], unknown, never>;
     /** The record stored with the current revision, if the source supplied one. */

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

@@ -1,5 +1,5 @@
 /** Validate both sides of a tool's form and bind delivery to its invocation lifetime. */
-import { Effect, Schema } from "effect";
+import { Effect, Schema, type Context } from "effect";
 import { ElicitationFailed, type ElicitationHandler, type Elicit } from "../contracts/elicitation.js";
 /** Parse a form and retain its response parser, so invalid answers can be rejected before consuming a host continuation. */
 export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
@@ -12,15 +12,15 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                 readonly [x: string]: {
                     readonly type: "string";
                     readonly enum: readonly string[];
-                    readonly default?: string;
                     readonly description?: string;
+                    readonly default?: string;
                     readonly title?: string;
                     readonly enumNames?: readonly string[];
                 } | {
                     readonly type: "string";
                     readonly enum: readonly string[];
-                    readonly default?: string;
                     readonly description?: string;
+                    readonly default?: string;
                     readonly title?: string;
                 } | {
                     readonly type: "string";
@@ -28,8 +28,8 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                         readonly const: string;
                         readonly title: string;
                     }[];
-                    readonly default?: string;
                     readonly description?: string;
+                    readonly default?: string;
                     readonly title?: string;
                 } | {
                     readonly type: "array";
@@ -37,11 +37,11 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                         readonly type: "string";
                         readonly enum: readonly string[];
                     };
-                    readonly default?: readonly string[];
                     readonly description?: string;
-                    readonly title?: string;
+                    readonly default?: readonly string[];
                     readonly minItems?: number;
                     readonly maxItems?: number;
+                    readonly title?: string;
                 } | {
                     readonly type: "array";
                     readonly items: {
@@ -50,30 +50,30 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                             readonly title: string;
                         }[];
                     };
-                    readonly default?: readonly string[];
                     readonly description?: string;
-                    readonly title?: string;
+                    readonly default?: readonly string[];
                     readonly minItems?: number;
                     readonly maxItems?: number;
+                    readonly title?: string;
                 } | {
                     readonly type: "string";
+                    readonly description?: string;
                     readonly default?: string;
                     readonly format?: "email" | "uri" | "date" | "date-time";
-                    readonly description?: string;
-                    readonly title?: string;
                     readonly minLength?: number;
                     readonly maxLength?: number;
+                    readonly title?: string;
                 } | {
                     readonly type: "number" | "integer";
+                    readonly description?: string;
                     readonly default?: number;
+                    readonly minimum?: number;
                     readonly maximum?: number;
-                    readonly description?: string;
                     readonly title?: string;
-                    readonly minimum?: number;
                 } | {
                     readonly type: "boolean";
-                    readonly default?: boolean;
                     readonly description?: string;
+                    readonly default?: boolean;
                     readonly title?: string;
                 };
             };
@@ -99,5 +99,8 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
         } | undefined;
     }, ElicitationFailed, never>;
 }, ElicitationFailed, never>;
-/** Bind a validated interaction to the live invocation; transport adapters share its form parser. */
-export declare const makeElicit: (handler: ElicitationHandler | undefined, signal: AbortSignal) => Elicit;
+/**
+ * Bind a validated interaction to the live invocation; transport adapters share its form parser.
+ * Authored code's Promise calls run in the invocation's telemetry, like framework callers.
+ */
+export declare const makeElicit: (handler: ElicitationHandler | undefined, signal: AbortSignal, telemetry: Context.Context<never>) => Elicit;

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

@@ -0,0 +1,59 @@
+/** Event declarations and the per-invocation emitter. Emitted events leave in the reply. */
+import { Effect, Schema as EffectSchema } from "effect";
+import { EmittedEvent, type AppEvent, type EmitOptions } from "../contracts/events.js";
+import { type Fields, type Infer, type ObjectValue, type Schema } from "./schema.js";
+declare const Native: unique symbol;
+/** An event an app emits. Declare it in `defineApp`'s requirements under `events`. */
+export interface EventDeclaration<F extends Fields, P extends Schema<unknown, boolean>> {
+    readonly [Native]: AppEvent;
+    readonly description: string;
+    readonly filters: F;
+    readonly payload: P;
+}
+/** Any declared event, for requirement constraints. */
+export type AnyEventDeclaration = EventDeclaration<Fields, Schema<unknown, boolean>>;
+/**
+ * Declare an event. `filters` are scalar fields subscribers can narrow on, such as a repository;
+ * every emitted occurrence supplies their values. `payload` describes each occurrence's data.
+ */
+export declare const event: <const F extends Fields = {}, P extends Schema<unknown, boolean> = Schema<unknown>>(options: {
+    readonly description: string;
+    readonly filters?: F;
+    readonly payload: P;
+}) => EventDeclaration<F, P>;
+/** The native declaration retained by an author event. */
+export declare const nativeEvent: (declaration: unknown) => AppEvent | undefined;
+/** JSON Schema for each declared event, as the host reads it from requirements. */
+export declare const declaredEvents: (events: Readonly<Record<string, AppEvent>>) => Effect.Effect<{
+    readonly [x: string]: {
+        readonly description: string;
+        readonly filters: {
+            readonly [x: string]: EffectSchema.Json;
+        };
+        readonly payload: {
+            readonly [x: string]: EffectSchema.Json;
+        };
+    };
+}, EffectSchema.SchemaError, never>;
+/** Emit options typed by the event's filters: required exactly when it declares some. */
+type OptionsFor<F extends Fields> = keyof F extends never ? [options?: Omit<EmitOptions<never>, "filters">] : [options: EmitOptions<ObjectValue<F>> & {
+    readonly filters: ObjectValue<F>;
+}];
+/** `ctx.events` in mutations and webhook handlers. */
+export interface EventEmitter<Events extends Readonly<Record<string, AnyEventDeclaration>>> {
+    /**
+     * Record an occurrence. It is delivered only if this invocation succeeds. Invalid data, filters
+     * or options throw here, before anything is recorded.
+     */
+    readonly emit: <Name extends keyof Events & string>(name: Name, data: Infer<Events[Name]["payload"]>, ...options: OptionsFor<Events[Name]["filters"]>) => void;
+}
+/** One invocation's buffer. The handler reads `emitted` only after the invocation succeeds. */
+export declare const makeEmitter: (input: {
+    readonly events: Readonly<Record<string, AppEvent>>;
+    /** Every account ID bound to this invocation. */
+    readonly accounts: readonly string[];
+    /** The webhook's source account, which an emit names by default. */
+    readonly sourceAccount?: string;
+    readonly emitted: EmittedEvent[];
+}) => EventEmitter<Readonly<Record<string, AnyEventDeclaration>>>;
+export {};

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

@@ -1,11 +1,14 @@
-import { Redacted } from "effect";
-import type { ResolvedAccounts } from "../contracts/host.js";
+import { Option, Redacted } from "effect";
+import { McpError as HostMcpError, SkillLoadFailed as HostSkillLoadFailed, type ResolvedAccounts } from "../contracts/host.js";
+import type { ProviderError } from "../contracts/provider-error.js";
+import { type FailureFields, type FailurePhase, type UpstreamError } from "../contracts/failure.js";
 /** Fields of `FailureDetail` as constructor input. */
 export interface FailureDetail {
     readonly source?: "app" | "storage" | "service";
     readonly errorName?: string;
     readonly code?: string;
     readonly message?: string;
+    readonly fields?: FailureFields;
 }
 /**
  * Every credential field value of a slot-to-account record, longest first. Accepts both resolved
@@ -16,10 +19,29 @@ export declare const accountFieldSecrets: (accounts: unknown) => string[];
 export declare const accountSecrets: (accounts: Redacted.Redacted<ResolvedAccounts>) => string[];
 /** Replace account secrets and bound the message for the runtime boundary. */
 export declare const boundFailureMessage: (message: string, secrets: readonly string[]) => string;
+/**
+ * Replace account secrets in the error a service stated, as it leaves the bundle. A message
+ * shortened where it was read can end partway through a secret; that part is replaced too.
+ */
+export declare const redactUpstream: (upstream: UpstreamError | undefined, secrets: readonly string[]) => UpstreamError | undefined;
+/**
+ * A provider failure as it leaves the bundle: in the phase it happened, unless its raiser named a
+ * more precise one, with account secrets replaced in the error the service stated.
+ */
+export declare const leavingProviderError: (error: ProviderError, secrets: readonly string[], phase?: FailurePhase) => ProviderError;
+/**
+ * Rebuild an MCP failure's allowlisted fields, with account secrets replaced in the server's
+ * error. Absent fields have no key, as catalogs cross the boundary as JSON values.
+ */
+export declare const parseMcpError: (error: unknown, secrets: readonly string[]) => Option.Option<HostMcpError>;
+/** Rebuild only the allowlisted skill loader fields from an author-visible rejection. */
+export declare const parseSkillLoadFailed: (error: unknown) => Option.Option<HostSkillLoadFailed>;
 /** `Name: message` for any thrown value, before redaction. */
 export declare const describeFailure: (error: unknown) => string;
 /**
  * Describe what an operation raised for the app's own caller. App data failures keep their
- * reason as a code; any other thrown value is the app's own error. Account secrets are replaced.
+ * reason as a code, as do app cache failures and OpenAPI and MCP service failures, such as an
+ * `mcpHealth` check that cannot reach its server or cannot verify the credentials; any other thrown
+ * value is the app's own error, with its own code and scalar fields. Account secrets are replaced.
  */
 export declare const failureDetail: (error: unknown, secrets: readonly string[]) => FailureDetail;

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

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 import { GraphqlToolsOptions } from "../contracts/graphql.js";
-import { type CatalogCacheOptions } from "./catalog-cache.js";
+import { type CatalogAccount, type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
-export interface GraphqlCatalogOptions extends GraphqlToolsOptions, CatalogCacheOptions {
-}
+/** An endpoint, the account whose schema it is, and the metadata policy. */
+export type GraphqlCatalogOptions = Omit<GraphqlToolsOptions, "accountId" | "headers"> & CatalogCacheOptions & CatalogAccount;
 export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -1,4 +1,5 @@
 import { ProviderError } from "../contracts/provider-error.js";
+import { NetworkRefused } from "../contracts/network.js";
 /** Discover GraphQL tools live; transport, decoding and cancellation stay in Effect. */
 import { Effect, Schema } from "effect";
 import { OperationTypeNode } from "graphql";
@@ -8,7 +9,7 @@ import { JsonObject } from "../effect.js";
 export declare const graphqlClientEffect: (input: GraphqlToolsOptions) => Effect.Effect<{
     request: (phase: "discover" | "call", query: string, variables?: JsonObject) => Effect.Effect<{
         readonly [x: string]: Schema.Json;
-    }, ProviderError | GraphqlError, never>;
+    }, ProviderError | NetworkRefused | GraphqlError, never>;
     discover: Effect.Effect<{
         readonly __schema: {
             readonly queryType: {
@@ -42,7 +43,7 @@ export declare const graphqlClientEffect: (input: GraphqlToolsOptions) => Effect
                 }[] | null;
             }[];
         };
-    }, ProviderError | GraphqlError, never>;
+    }, ProviderError | NetworkRefused | GraphqlError, never>;
 }, GraphqlError, never>;
 /** Build serializable definitions once per introspection revision, without compiling validators. */
 export declare const graphqlDefinitions: (catalog: GraphqlIntrospection) => Effect.Effect<{
@@ -80,4 +81,4 @@ export declare const graphqlDefinitions: (catalog: GraphqlIntrospection) => Effe
 /** Bind only the selected definition to current credentials and compile its input decoder. */
 export declare const adaptGraphqlTool: (client: Effect.Success<ReturnType<typeof graphqlClientEffect>>, definition: GraphqlToolDefinition) => Effect.Effect<import("../contracts/graphql.js").GraphqlTool, GraphqlError, never>;
 /** Low-level callers can still request a complete invocation-owned tool map. */
-export declare const graphqlToolsEffect: (input: GraphqlToolsOptions) => Effect.Effect<GraphqlTools, GraphqlError | ProviderError>;
+export declare const graphqlToolsEffect: (input: GraphqlToolsOptions) => Effect.Effect<GraphqlTools, GraphqlError | ProviderError | NetworkRefused>;

package/types/apps/src/implementation/input-problems.d.ts

@@ -1,3 +1,7 @@
 import { HostInputInvalid } from "../contracts/host.js";
-/** Failing input paths and expected shapes from a schema decode failure, without supplied values. */
-export declare const inputInvalid: (error: unknown) => HostInputInvalid;
+/**
+ * Failing input paths and what each expects, from a schema decode failure, without supplied
+ * values. An expected object names its keys, so a caller can correct nesting from the problem.
+ * A missing key also asks about a place where `input`, the rejected input, may have that key.
+ */
+export declare const inputInvalid: (error: unknown, input: unknown) => HostInputInvalid;

package/types/apps/src/implementation/invocation-timing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Divide a tool invocation's time, on its own isolate's clock, by who the work belonged to:
+ * Executor, the app's authored code, upstream providers, a person answering an elicitation, or
+ * another call loading a cache entry this one waits for. Background work no caller waits on runs
+ * beside the division and is reported apart.
+ * Each boundary declares its owner where the work starts (see `owned`); the invocation's own span is
+ * Executor's. The host adds the other isolates' parts.
+ */
+import { Effect } from "effect";
+/** The span `makeElicit` opens while a person answers. */
+export declare const elicitationWaitSpan = "app.elicitation.wait";
+/** The span around each workflow control an app calls, which Executor answers. */
+export declare const workflowControlSpan = "app.workflow.control";
+/**
+ * Run a tool operation in its `app.<operation>` span and time it from the span's own start to its
+ * own end. The span records each part, and the isolated handler returns them to the host.
+ */
+export declare const timedInvocation: (operation: "call" | "query" | "mutate") => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, import("effect/Tracer").ParentSpan>>;

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

@@ -1,4 +1,4 @@
-import { Atom } from "effect/unstable/reactivity";
+import { Atom } from "effect/reactivity";
 import { AppQueryFailed, type OperationReference, type QueryTransport } from "../contracts/live.js";
 import type { Operation } from "./operations.js";
 import { type Schema } from "./schema.js";
@@ -14,5 +14,5 @@ export declare const mutationReference: <Mutation>(name: Mutation extends Operat
 export declare const liveQueryAtom: <Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, options: {
     readonly output: Schema<NoInfer<Output>, boolean>;
     readonly transport: QueryTransport;
-}) => Atom.Atom<import("effect/unstable/reactivity/AsyncResult").AsyncResult<NoInfer<Output>, import("effect/Cause").NoSuchElementError | AppQueryFailed>>;
+}) => Atom.Atom<import("effect/reactivity/AsyncResult").AsyncResult<NoInfer<Output>, import("effect/Cause").NoSuchElementError | AppQueryFailed>>;
 export {};

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "../contracts/provider-error.js";
+import type { NetworkRefused } from "../contracts/network.js";
 /** One upstream call, with form requests forwarded to the invocation's existing elicitation capability. */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { Effect, Schema } from "effect";
@@ -6,15 +7,15 @@ import { ElicitationFailed } from "../contracts/elicitation.js";
 import { McpError, type McpToolContext } from "../contracts/mcp.js";
 import type { JsonObject } from "../contracts/schema.js";
 /** Register prompts only around tools/call, preserve metadata, and close every callback with the call. Never retries. */
-export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError) => Effect.Effect<{
+export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError | NetworkRefused) => Effect.Effect<{
     readonly content: readonly {
         readonly [x: string]: Schema.Json;
     }[];
     readonly _meta?: {
         readonly [x: string]: Schema.Json;
-    } | undefined;
+    };
     readonly structuredContent?: {
         readonly [x: string]: Schema.Json;
-    } | undefined;
-    readonly isError?: boolean | undefined;
-}, ProviderError | ElicitationFailed | McpError, never>;
+    };
+    readonly isError?: boolean;
+}, ProviderError | NetworkRefused | ElicitationFailed | McpError, never>;

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

@@ -1,9 +1,11 @@
 import { Effect } from "effect";
 import { McpToolsOptions } from "../contracts/mcp.js";
-import { type CatalogCacheOptions } from "./catalog-cache.js";
+import { type CatalogAccount, type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
-/** Metadata policy for HTTP/SSE sources. A missing cache keeps discovery invocation-local. */
-export interface McpCatalogOptions extends McpToolsOptions, CatalogCacheOptions {
-}
+/**
+ * A server, the account whose catalog it is, and the metadata policy for HTTP/SSE sources. A
+ * missing cache keeps discovery invocation-local.
+ */
+export type McpCatalogOptions = Omit<McpToolsOptions, "accountId" | "headers"> & CatalogCacheOptions & CatalogAccount;
 /** Construction opens no transport unless explicit revalidation is requested. */
 export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;