apps 0.0.1-beta.4 → 0.0.1-beta.41

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";
@@ -24,14 +25,38 @@ export declare const WorkflowStepOptions: Schema.Struct<{
     readonly timeout: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>>;
 }>;
 export type WorkflowStepOptions = typeof WorkflowStepOptions.Type;
+/**
+ * Where and why a run failed: the failing step and the error the app's own code raised, its
+ * message bounded and with account secrets replaced. Runs from before these fields existed have none.
+ */
+export declare const WorkflowFailureDetail: {
+    step: Schema.optionalKey<Schema.String>;
+    errorName: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+};
+/** A failed run's recorded step and app error. */
+export declare const WorkflowRunFailure: Schema.Struct<{
+    step: Schema.optionalKey<Schema.String>;
+    errorName: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+}>;
+export type WorkflowRunFailure = typeof WorkflowRunFailure.Type;
 declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedStruct<"WorkflowFailure", {
     readonly reason: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
     readonly retryable: Schema.Boolean;
+    readonly step: Schema.optionalKey<Schema.String>;
+    readonly errorName: Schema.optionalKey<Schema.String>;
+    readonly message: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
-/** Safe failures cross host boundaries without authored exceptions or account fields. */
+/** 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 stays inside the app runtime. */
+/** Explicitly stop retrying an authored step. Its message is reported like any step error. */
 export declare class NonRetryableError extends Error {
     readonly name = "NonRetryableError";
 }
@@ -45,7 +70,7 @@ export declare const HostedWorkflow: Schema.Struct<{
     readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type HostedWorkflow = typeof HostedWorkflow.Type;
-/** Results are available only on completed runs; failure details are safe reason codes. */
+/** Results are available only on completed runs; failures carry a reason code and app error detail. */
 export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
     readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
     readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
@@ -66,6 +91,12 @@ export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
 }>, Schema.Struct<{
     readonly status: Schema.Literal<"errored">;
     readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+    /** The failing step and the app's own error, when the run recorded them. */
+    readonly failure: Schema.optionalKey<Schema.Struct<{
+        step: Schema.optionalKey<Schema.String>;
+        errorName: Schema.optionalKey<Schema.String>;
+        message: Schema.optionalKey<Schema.String>;
+    }>>;
     readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
@@ -104,6 +135,12 @@ export declare const WorkflowRunPage: Schema.Struct<{
     }>, Schema.Struct<{
         readonly status: Schema.Literal<"errored">;
         readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+        /** The failing step and the app's own error, when the run recorded them. */
+        readonly failure: Schema.optionalKey<Schema.Struct<{
+            step: Schema.optionalKey<Schema.String>;
+            errorName: Schema.optionalKey<Schema.String>;
+            message: Schema.optionalKey<Schema.String>;
+        }>>;
         readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;

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/graphql.d.ts

@@ -4,7 +4,5 @@ import { type GraphqlCatalogOptions } from "./implementation/graphql-catalog.js"
 export { GraphqlError, type GraphqlToolsOptions } from "./contracts/graphql.js";
 export type { GraphqlCatalogOptions } from "./implementation/graphql-catalog.js";
 /** Lazy tools with optional persistent metadata caching for the selected account. */
-export declare const graphqlOperations: (options: GraphqlCatalogOptions, kinds?: OperationKinds) => Promise<{
-    dynamicTools: import("./contracts/dynamic-tools.js").DynamicTools;
-}>;
+export declare const graphqlRouter: (options: GraphqlCatalogOptions, kinds?: OperationKinds) => Promise<import("./index.js").RouterDeclaration<unknown, unknown>>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";

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

@@ -0,0 +1,12 @@
+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.
+ */
+export declare const accountRouter: <Account extends {
+    readonly id: string;
+}>(accounts: readonly Account[], discover: (account: Account) => Promise<RouterDeclaration>, options: {
+    readonly signal: AbortSignal;
+}) => Promise<RouterDeclaration>;

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

@@ -4,7 +4,7 @@ import type { AppRequirements, AppContext, QueryContext, MutationContext, Webhoo
 import { type PromiseMethods } from "./authoring.js";
 import { type WorkflowDeclaration } from "./workflows.js";
 import type { WorkflowContext } from "../contracts/workflows.js";
-import { type OperationDeclaration } from "./operations.js";
+import { type RouterDeclaration } from "./router.js";
 import { type Schema } from "./schema.js";
 type PromiseCatalog<Catalog> = Catalog extends Readonly<Record<string, object>> ? {
     readonly [Name in keyof Catalog]: {
@@ -14,15 +14,16 @@ type PromiseCatalog<Catalog> = Catalog extends Readonly<Record<string, object>>
 /** Author definition projected from native capabilities. Excluding callable objects keeps
  * factories from being inferred as definitions and preserves contextual handler inference. */
 export type AppDefinition<Requirements extends AppRequirements> = {
-    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>>>> : Key extends "schedules" ? Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>>>> : Key extends "queries" ? Readonly<Record<string, OperationDeclaration<"query", QueryContext<Requirements>>>> : Key extends "mutations" ? Readonly<Record<string, OperationDeclaration<"mutation", MutationContext<Requirements>>>> : Key extends "webhooks" ? PromiseCatalog<NonNullable<NativeDefinition<WebhookContext<Requirements>>[Key]>> : NativeDefinition<WebhookContext<Requirements>>[Key];
+    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>>>> : Key extends "schedules" ? Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>>>> : Key extends "tools" ? RouterDeclaration<QueryContext<Requirements>, MutationContext<Requirements>> : Key extends "webhooks" ? PromiseCatalog<NonNullable<NativeDefinition<WebhookContext<Requirements>>[Key]>> : NativeDefinition<WebhookContext<Requirements>>[Key];
 } & {
     readonly name?: never;
-    readonly tools?: never;
+    readonly queries?: never;
+    readonly mutations?: never;
     readonly call?: never;
 };
 /** Adapt operation and webhook catalogs without evaluating their handlers. */
 export type EffectDefinition<Def> = {
-    readonly [Key in keyof Def]: Key extends "dynamicTools" ? NonNullable<NativeDefinition<unknown>["dynamicTools"]> : Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "queries" | "mutations" ? Readonly<Record<string, import("../contracts/operations.js").AppOperation>> : Key extends "webhooks" ? NonNullable<NativeDefinition<WebhookContext>["webhooks"]> : Key extends "skills" ? NonNullable<NativeDefinition<unknown>["skills"]> : Key extends "dynamicSkills" ? NonNullable<NativeDefinition<unknown>["dynamicSkills"]> : Def[Key];
+    readonly [Key in keyof Def]: Key extends "tools" ? NonNullable<NativeDefinition<unknown>["tools"]> : Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "webhooks" ? NonNullable<NativeDefinition<WebhookContext>["webhooks"]> : Key extends "skills" ? NonNullable<NativeDefinition<unknown>["skills"]> : Key extends "dynamicSkills" ? NonNullable<NativeDefinition<unknown>["dynamicSkills"]> : Def[Key];
 };
 declare const InternalApp: unique symbol;
 /** Recognize a declaration from this framework instance before host adaptation. */

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 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();})();";
+/** 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/catalog-cache.d.ts

@@ -1,8 +1,8 @@
 import { Duration, Effect, Schema } from "effect";
-import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
-import { type JsonValue } from "../contracts/schema.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,9 +11,34 @@ 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;
+}
 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. */
@@ -21,9 +46,11 @@ export declare const catalogCache: <A extends {
         readonly schema: Schema.Decoder<S>;
         readonly of: (tool: A) => S;
     };
-    readonly load: (context?: CacheLoadContext) => Effect.Effect<readonly A[], unknown>;
+    readonly load: (context?: CacheLoadContext) => 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. */
+    header: () => Effect.Effect<JsonObject | undefined, unknown>;
     summaries: () => Effect.Effect<S[], unknown, never>;
     resolve: (name: string) => Effect.Effect<A | undefined, unknown, never>;
 }, unknown, never>;

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

@@ -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 default?: number;
                     readonly description?: string;
-                    readonly title?: string;
+                    readonly default?: number;
                     readonly minimum?: number;
                     readonly maximum?: number;
+                    readonly title?: string;
                 } | {
                     readonly type: "boolean";
-                    readonly default?: boolean;
                     readonly description?: string;
+                    readonly default?: boolean;
                     readonly title?: string;
                 };
             };

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

@@ -0,0 +1,47 @@
+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
+ * host accounts and bound author accounts; each account keeps its credential values in `fields`.
+ */
+export declare const accountFieldSecrets: (accounts: unknown) => string[];
+/** Every credential field value of an invocation's selected accounts. */
+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, 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,10 +1,7 @@
 import { Effect } from "effect";
 import { GraphqlToolsOptions } from "../contracts/graphql.js";
-import type { DynamicTools } from "../contracts/dynamic-tools.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 {
-}
-export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+/** 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/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,12 +1,11 @@
 import { Effect } from "effect";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 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<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -1,51 +1,75 @@
 import type { ProviderError } from "../contracts/provider-error.js";
+import type { NetworkRefused } from "../contracts/network.js";
 /** Shared MCP pagination, wire parsing and calls. Transport owns connection lifetime. */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { jsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/types.js";
 import { Effect, Schema } from "effect";
 import { McpError, type McpToolContext } from "../contracts/mcp.js";
+import type { UpstreamError } from "../contracts/failure.js";
 import type { JsonObject } from "../effect.js";
+/**
+ * The JSON-RPC error a server answered a request with, if `error` is one. The SDK formats its
+ * message as `MCP error <code>: <message>`; the server's own message follows that prefix.
+ */
+export declare const answeredError: (error: unknown) => UpstreamError | undefined;
 /** Use the framework-owned interpreter at the MCP SDK's synchronous validation boundary. */
 export declare const mcpJsonSchemaValidator: jsonSchemaValidator;
 /** An operation owns its connection; it must close even when interrupted. */
 export interface WithMcpClient {
-    <A, E>(mode: "discover" | "call", use: (client: Client) => Effect.Effect<A, E>): Effect.Effect<A, E | McpError | ProviderError>;
+    <A, E>(mode: "discover" | "call", use: (client: Client) => Effect.Effect<A, E>): Effect.Effect<A, E | McpError | ProviderError | NetworkRefused>;
 }
 /** Shared client operations never cache catalogs or account credentials. */
-export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError): {
+export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError | NetworkRefused): {
     list: Effect.Effect<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly description?: string;
+            readonly version?: string;
+            readonly name?: string;
+            readonly instructions?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, ProviderError | NetworkRefused | McpError, never>;
+    check: Effect.Effect<void, ProviderError | NetworkRefused | McpError, never>;
     call: (name: string, input: JsonObject, context: McpToolContext) => 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 | import("../index.js").ElicitationFailed | McpError, never>;
+        };
+        readonly isError?: boolean;
+    }, ProviderError | NetworkRefused | import("../index.js").ElicitationFailed | McpError, never>;
 };
 /** Transport-independent operations consumed by the app tool adapter. */
 export type McpClient = ReturnType<typeof mcpClient>;

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

@@ -1,4 +1,4 @@
 import { Effect } from "effect";
 import { McpError, ProcessConfig } from "../contracts/mcp.js";
 /** Each discovery/call owns and closes its subprocess. Deployment never starts it. */
-export declare const stdioToolsEffect: (input: ProcessConfig) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, import("../index.js").ProviderError | McpError, never>;
+export declare const stdioToolsEffect: (input: ProcessConfig) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, import("../index.js").ProviderError | import("../index.js").NetworkRefused | McpError, never>;

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "../contracts/provider-error.js";
+import type { NetworkRefused } from "../contracts/network.js";
 /** Adapt any MCP transport into ordinary tools with shared validation behavior. */
 import { Effect } from "effect";
 import { McpError, type McpTools, type McpToolMetadata } from "../contracts/mcp.js";
@@ -6,4 +7,4 @@ import type { McpClient } from "./mcp-client.js";
 /** Compile only the selected tool and bind its executable to the current invocation. */
 export declare const adaptMcpTool: (client: McpClient, tool: McpToolMetadata) => Effect.Effect<import("../contracts/mcp.js").McpTool, McpError, never>;
 /** Discover a complete catalog for probes and uncached low-level callers. */
-export declare const adaptMcpTools: (client: McpClient) => Effect.Effect<McpTools, McpError | ProviderError>;
+export declare const adaptMcpTools: (client: McpClient) => Effect.Effect<McpTools, McpError | ProviderError | NetworkRefused>;