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

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

@@ -1,7 +1,10 @@
 /** Portable workflow declarations, run views and durable execution capabilities. */
+import { withLegacyKeys } from "../../../utils/src/legacy-keys.js";
 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 { AccountScope } from "./app.js";
 import type { Operation } from "../implementation/operations.js";
 import type { HostContext } from "./host.js";
 /** Run identity is opaque and shared by author and SDK interfaces. */
@@ -24,14 +27,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,79 +72,102 @@ 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. */
-export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
+/**
+ * Results are available only on completed runs; failures carry a reason code and app error detail.
+ * Runs name their version under its former name too, for apps and callers written before the rename.
+ */
+export declare const WorkflowRun: Schema.Union<readonly [withLegacyKeys<Schema.Struct<{
     readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
-    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
-    readonly deployment: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
     readonly workflow: Schema.NonEmptyString;
     readonly createdAt: Schema.String;
-}>, Schema.Struct<{
+}>, {
+    readonly version: "deployment";
+}>, withLegacyKeys<Schema.Struct<{
     readonly status: Schema.Literal<"complete">;
     readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
-    readonly deployment: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
     readonly workflow: Schema.NonEmptyString;
     readonly createdAt: Schema.String;
-}>, Schema.Struct<{
+}>, {
+    readonly version: "deployment";
+}>, withLegacyKeys<Schema.Struct<{
     readonly status: Schema.Literal<"errored">;
     readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
-    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+    /** 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 id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
-    readonly deployment: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
     readonly workflow: Schema.NonEmptyString;
     readonly createdAt: Schema.String;
-}>, Schema.Struct<{
+}>, {
+    readonly version: "deployment";
+}>, withLegacyKeys<Schema.Struct<{
     readonly status: Schema.Literal<"terminated">;
-    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
-    readonly deployment: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
     readonly workflow: Schema.NonEmptyString;
     readonly createdAt: Schema.String;
+}>, {
+    readonly version: "deployment";
 }>]>;
 export type WorkflowRun = typeof WorkflowRun.Type;
 /** A bounded run-history page, already scoped to an authorized configured app. */
 export declare const WorkflowRunPage: Schema.Struct<{
-    readonly items: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Union<readonly [withLegacyKeys<Schema.Struct<{
         readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
-        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;
-        readonly deployment: Schema.NonEmptyString;
+        readonly version: Schema.NonEmptyString;
         readonly workflow: Schema.NonEmptyString;
         readonly createdAt: Schema.String;
-    }>, Schema.Struct<{
+    }>, {
+        readonly version: "deployment";
+    }>, withLegacyKeys<Schema.Struct<{
         readonly status: Schema.Literal<"complete">;
         readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;
-        readonly deployment: Schema.NonEmptyString;
+        readonly version: Schema.NonEmptyString;
         readonly workflow: Schema.NonEmptyString;
         readonly createdAt: Schema.String;
-    }>, Schema.Struct<{
+    }>, {
+        readonly version: "deployment";
+    }>, withLegacyKeys<Schema.Struct<{
         readonly status: Schema.Literal<"errored">;
         readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
-        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+        /** 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 id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;
-        readonly deployment: Schema.NonEmptyString;
+        readonly version: Schema.NonEmptyString;
         readonly workflow: Schema.NonEmptyString;
         readonly createdAt: Schema.String;
-    }>, Schema.Struct<{
+    }>, {
+        readonly version: "deployment";
+    }>, withLegacyKeys<Schema.Struct<{
         readonly status: Schema.Literal<"terminated">;
-        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;
-        readonly deployment: Schema.NonEmptyString;
+        readonly version: Schema.NonEmptyString;
         readonly workflow: Schema.NonEmptyString;
         readonly createdAt: Schema.String;
+    }>, {
+        readonly version: "deployment";
     }>]>>;
     readonly next: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "wfr">>;
 }>;
@@ -144,25 +194,28 @@ export interface WorkflowControls extends WorkflowReads {
         readonly run: string;
     }) => Promise<WorkflowRun>;
 }
-/** External steps get fresh credentials and cancellation, without storage or live elicitation. */
-export type WorkflowStepContext<Requirements extends AppRequirements = AppRequirements> = Omit<AppContext<Requirements>, "elicit" | "workflows"> & {
+/**
+ * External steps get fresh credentials and cancellation, without storage or live elicitation. A run
+ * started by app-scope work, such as an app schedule, has the `"app"` scope: no `user`.
+ */
+export type WorkflowStepContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = Omit<AppContext<Requirements, Scope>, "elicit" | "workflows"> & {
     readonly runId: WorkflowRunId;
     readonly stepId: string;
     readonly idempotencyKey: string;
 };
 /** Explicit durable boundaries; database access passes through registered app operations. */
-export interface WorkflowStep<Requirements extends AppRequirements = AppRequirements> {
-    do<Output>(name: string, run: (context: WorkflowStepContext<Requirements>) => Promise<Output>): Promise<Output>;
-    do<Output>(name: string, options: WorkflowStepOptions, run: (context: WorkflowStepContext<Requirements>) => Promise<Output>): Promise<Output>;
-    runQuery<Input, Output>(name: string, operation: Operation<Input, Output, "query", QueryContext<Requirements>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
-    runMutation<Input, Output>(name: string, operation: Operation<Input, Output, "mutation", MutationContext<Requirements>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
+export interface WorkflowStep<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> {
+    do<Output>(name: string, run: (context: WorkflowStepContext<Requirements, Scope>) => Promise<Output>): Promise<Output>;
+    do<Output>(name: string, options: WorkflowStepOptions, run: (context: WorkflowStepContext<Requirements, Scope>) => Promise<Output>): Promise<Output>;
+    runQuery<Input, Output>(name: string, operation: Operation<Input, Output, "query", QueryContext<Requirements, Scope>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
+    runMutation<Input, Output>(name: string, operation: Operation<Input, Output, "mutation", MutationContext<Requirements, Scope>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
     readonly sleep: (name: string, duration: WorkflowDuration) => Promise<void>;
     readonly sleepUntil: (name: string, timestamp: number | Date) => Promise<void>;
 }
 /** The orchestration body gets no account, database or interactive capabilities. */
-export interface WorkflowContext<Requirements extends AppRequirements = AppRequirements> {
+export interface WorkflowContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> {
     readonly runId: WorkflowRunId;
-    readonly step: WorkflowStep<Requirements>;
+    readonly step: WorkflowStep<Requirements, Scope>;
 }
 /** Framework-owned native declaration; only the callback crosses the author Promise boundary. */
 export interface AppWorkflow<Input = unknown, Output = unknown> {

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/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

@@ -0,0 +1,13 @@
+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. `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;
+}, Query = unknown, Mutation = unknown>(accounts: readonly Account[], discover: (account: Account) => RouterDeclaration<Query, Mutation> | Promise<RouterDeclaration<Query, Mutation>>, options: {
+    readonly signal: AbortSignal;
+}) => Promise<RouterDeclaration<Query, Mutation>>;

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

@@ -1,40 +1,68 @@
 import type { ScheduleDeclaration } from "./schedules.js";
-import type { App as NativeApp, AppDefinition as NativeDefinition } from "../contracts/app.js";
-import type { AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext } from "../contracts/context.js";
+import type { App as NativeApp, AccountScope, AppDefinition as NativeDefinition, EvaluationContext } from "../contracts/app.js";
+import type { AppRequirements, QueryContext, MutationContext, RequirementSlots, WebhookContext } from "../contracts/context.js";
 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]: {
-        readonly [Key in keyof Catalog[Name]]: Key extends "config" | "state" ? Schema<unknown, boolean> : PromiseMethods<Catalog[Name]>[Key];
-    };
-} : Catalog;
+/** One native webhook definition with the given handler context. */
+type NativeWebhook<Context> = NonNullable<NativeDefinition<Context>["webhooks"]>[string];
+/** A webhook as authors write it: Promise handlers, author schemas and its source requirement. */
+type AuthorWebhook<Context, Account> = {
+    readonly [Key in keyof NativeWebhook<Context>]: Key extends "config" | "state" ? Schema<unknown, boolean> : Key extends "account" ? Account : PromiseMethods<NativeWebhook<Context>>[Key];
+};
+/**
+ * A user-account webhook gets the caller-shaped context; an app-account webhook runs without a
+ * caller, so its context has no `user`.
+ */
+type AuthorWebhooks<Requirements extends AppRequirements> = Readonly<Record<string, AuthorWebhook<WebhookContext<Requirements>, {
+    readonly user: keyof RequirementSlots<Requirements>["user"] & string;
+}> | AuthorWebhook<WebhookContext<Requirements, "app">, {
+    readonly app: keyof RequirementSlots<Requirements>["app"] & string;
+}>>>;
+/**
+ * User schedules run as each member who enables them; app schedules run without a caller, so their
+ * mutation takes a context of the `"app"` scope.
+ */
+type AuthorSchedules<Requirements extends AppRequirements> = Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>, "user"> | ScheduleDeclaration<MutationContext<Requirements, "app">, "app">>>;
+/**
+ * A run started by a caller binds its accounts; one started without a caller, such as by an app
+ * schedule, has no `user`, so its workflow declares a context of the `"app"` scope.
+ */
+type AuthorWorkflows<Requirements extends AppRequirements> = Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>> | WorkflowDeclaration<WorkflowContext<Requirements, "app">>>>;
 /** 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" ? AuthorWorkflows<Requirements> : Key extends "schedules" ? AuthorSchedules<Requirements> : Key extends "tools" ? RouterDeclaration<QueryContext<Requirements>, MutationContext<Requirements>> : Key extends "webhooks" ? AuthorWebhooks<Requirements> : NativeDefinition<WebhookContext<Requirements>>[Key];
 } & {
     readonly name?: never;
-    readonly tools?: never;
+    readonly queries?: never;
+    readonly mutations?: never;
     readonly call?: never;
 };
+/** A webhook context as the host builds it: an app-account hook's has no `user`. */
+type HostWebhookContext = WebhookContext<AppRequirements, AccountScope> & Partial<Pick<WebhookContext, "user">>;
 /** 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<HostWebhookContext>["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. */
 export declare const isApp: (value: unknown) => value is App<AppRequirements, AppDefinition<AppRequirements>>;
 /** Public app handle; the native app is retained for host use without an async round trip. */
 export interface App<Requirements extends AppRequirements, Def extends AppDefinition<Requirements>> {
-    readonly [InternalApp]: NativeApp<Requirements["accounts"], EffectDefinition<Def>>;
-    readonly accounts: Requirements["accounts"];
-    readonly evaluate: (context: AppContext<Requirements>) => Promise<Def>;
+    readonly [InternalApp]: NativeApp<RequirementSlots<Requirements>, EffectDefinition<Def>>;
+    readonly accounts: RequirementSlots<Requirements>;
+    readonly evaluate: (context: AppFactoryContext<Requirements>) => Promise<Def>;
 }
+/**
+ * What a dynamic definition's factory receives. App-scope work, such as an app schedule, evaluates
+ * the app without a caller, so `user` is absent then.
+ */
+export type AppFactoryContext<Requirements extends AppRequirements> = EvaluationContext<RequirementSlots<Requirements>>;
 /** Retrieve the same declaration for an Effect host. No evaluation or I/O occurs. */
-export declare const toEffectApp: <Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(app: App<Requirements, Def>) => NativeApp<Requirements["accounts"], EffectDefinition<Def>>;
+export declare const toEffectApp: <Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(app: App<Requirements, Def>) => NativeApp<RequirementSlots<Requirements>, EffectDefinition<Def>>;
 /** Assemble app behavior. Package names belong in package.json; hosts name installed copies. */
-export declare const defineApp: <const Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(requirements: Requirements, definition: (Def & AppDefinition<Requirements>) | ((context: AppContext<Requirements>) => Promise<Def & AppDefinition<Requirements>>)) => App<Requirements, Def>;
+export declare const defineApp: <const Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(requirements: Requirements, definition: (Def & AppDefinition<Requirements>) | ((context: AppFactoryContext<Requirements>) => Promise<Def & AppDefinition<Requirements>>)) => App<Requirements, Def>;
 export {};

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 c=()=>{let s=document.getElementById(\"executor-context\")?.textContent;if(!s)return;let n=JSON.parse(s);if(typeof n!=\"object\"||n===null||!(\"version\"in n))return;let r=n.version;if(typeof r!=\"string\"||r.length===0)return;let t=new EventSource(\"/_executor/version\"),d=!1,o=()=>{d||(d=!0,t.close(),location.reload())};t.addEventListener(\"version\",i=>{let e=JSON.parse(i.data);typeof e==\"object\"&&e!==null&&\"version\"in e&&(e.version===null||typeof e.version==\"string\")&&e.version!==r&&o()}),t.addEventListener(\"revoked\",o),window.addEventListener(\"executor:deployment-changed\",o),window.addEventListener(\"pagehide\",()=>t.close(),{once:!0}),window.addEventListener(\"pageshow\",i=>{i.persisted&&o()})};c();})();";
+/** 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,6 +1,35 @@
-import type { AppCache, HostCache } from "../contracts/cache.js";
-import type { ResolvedAccounts } from "../contracts/host.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) => AppCache;
+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 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,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. */
@@ -21,9 +51,17 @@ 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>;
+    /** 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. */
+    header: () => Effect.Effect<JsonObject | undefined, unknown>;
     summaries: () => Effect.Effect<S[], unknown, never>;
     resolve: (name: string) => Effect.Effect<A | undefined, unknown, never>;
 }, unknown, never>;