apps 0.0.1-beta.7 → 0.0.1-beta.73

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

@@ -1,4 +1,5 @@
 export { ProviderError } from "./contracts/provider-error.js";
+export { FetchOptionUnsupported, NetworkRefused } from "./contracts/network.js";
 export type { AppCache, CacheLoadContext, CacheGetOptions } from "./contracts/cache.js";
 export { CacheError } from "../../app-cache/src/contracts/cache.js";
 /**
@@ -8,40 +9,76 @@ export { CacheError } from "../../app-cache/src/contracts/cache.js";
 import { type Schema as EffectSchema } from "effect";
 import type { WebhookContext } from "./contracts/context.js";
 import { type JsonResponse as NativeResponse } from "./contracts/http.js";
-import { type OAuth2Config, type OAuth2Method as NativeOAuth2Method, type SecretsMethod as NativeSecretsMethod } from "./contracts/provider.js";
+import { type OAuth2Config as NativeOAuth2Config, type OAuth2Method as NativeOAuth2Method, type ReservedAuthorizationParam, type SecretsMethod as NativeSecretsMethod } from "./contracts/provider.js";
 import type { Webhook as NativeWebhook } from "./contracts/webhooks.js";
 import { type PromiseMethods } from "./implementation/authoring.js";
-import { type Fields, type Infer, type ObjectSchema, type Schema } from "./implementation/schema.js";
+import { type PlacementInput, type RequestPlacements } from "./implementation/placement.js";
+import type { Placement } from "./contracts/placement.js";
+import type { AppContext as NativeAppContext, QueryContext as NativeQueryContext } from "./contracts/context.js";
+import { query as operationQuery, type OperationOptions } from "./implementation/operations.js";
+import { type Fields, type Infer, type ObjectSchema, type Schema, type SecretFields, type SecretObject } from "./implementation/schema.js";
 export { type JsonObject, type JsonValue, ValidationError } from "./contracts/schema.js";
-export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Schema, array, boolean, json, jsonSchema, literal, number, object, record, string, } from "./implementation/schema.js";
-export { type AccountCheckContext, type AccountCheckResult, type AccountInfo, type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type OAuth2Config, type Provider, } from "./contracts/provider.js";
+export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Schema, array, boolean, json, jsonSchema, literal, number, object, record, string, plain, raw, type SecretString, } from "./implementation/schema.js";
+export { type AccountCheckContext, type AccountCheckResult, type AccountInfo, type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type Provider, type ReservedAuthorizationParam, } from "./contracts/provider.js";
 export { defineProvider, type ProviderOptions } from "./implementation/provider.js";
+export { base64, basic, bearer, header, t, type FieldRef, type FieldRefs, type PlacementInput, type PlacementValue, type RequestPlacements, } from "./implementation/placement.js";
+export type { Placement };
+export type { AccountRequest } from "./contracts/provider.js";
 export { accountRouter } from "./implementation/account-router.js";
-export { router, dynamicRouter, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
+export { router, dynamicRouter, withApprovals, type OperationChild, type OperationDeclaration, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
 export type { RouterIcon } from "./contracts/router.js";
 export { dynamicSkills } from "./implementation/dynamic-skills.js";
 export type { HostedTool as OperationDescription } from "./contracts/host.js";
+/** Account fields as app code receives them from a method declared with this schema. */
+type AccountFields<S> = S extends ObjectSchema<infer F> ? SecretFields<F> : SecretObject<Infer<S>>;
 /** A secrets declaration inferred from an author schema. */
-export type SecretsMethod<Shape extends ObjectSchema<Fields>> = NativeSecretsMethod<EffectSchema.Decoder<Infer<Shape>>>;
+export type SecretsMethod<Shape extends ObjectSchema<Fields>> = NativeSecretsMethod<EffectSchema.Decoder<AccountFields<Shape>>>;
 /** An OAuth declaration inferred from its author-facing response schema. */
-export type OAuth2Method<Response extends Schema<unknown, boolean>> = NativeOAuth2Method<EffectSchema.Decoder<Infer<Response>>>;
+export type OAuth2Method<Response extends Schema<unknown, boolean>> = NativeOAuth2Method<EffectSchema.Decoder<AccountFields<Response>>>;
+/** The names of an object schema's fields, which a method's `request` can reference. */
+type FieldNameOf<S> = S extends ObjectSchema<infer F> ? keyof F & string : never;
 /** Default OAuth fields visible to app code. Host-only grants and clients stay private. */
 export declare const OAuth2AccessToken: Schema<{
     readonly access_token: string;
 }, false>;
-/** Declare a secrets method without requiring an Effect schema from the author. */
+/**
+ * OAuth options as authors write them. `authorizationParams` naming a host-owned protocol
+ * parameter such as `state` or `scope` is a type error as well as a declaration failure.
+ */
+export type OAuth2Config = WithoutReservedParams<NativeOAuth2Config>;
+type WithoutReservedParams<Config> = Config extends unknown ? "authorizationParams" extends keyof Config ? Config & {
+    readonly authorizationParams?: {
+        readonly [Key in ReservedAuthorizationParam]?: never;
+    };
+} : Config : never;
+/**
+ * Declare a secrets method without requiring an Effect schema from the author. `request` says
+ * where its secret fields may be sent, such as `({ token }) => bearer(token)`; it runs once, here.
+ */
 export declare const secrets: <const F extends Fields>(options: {
     readonly label: string;
     readonly fields: ObjectSchema<F>;
+    readonly request?: RequestPlacements<keyof F & string>;
 }) => SecretsMethod<ObjectSchema<F>>;
-/** Declare OAuth discovery/endpoints and an optional app-visible response projection. */
-export declare function oauth2(options: OAuth2Config): OAuth2Method<typeof OAuth2AccessToken>;
+/**
+ * Declare OAuth discovery/endpoints and an optional app-visible response projection.
+ * `authorizationParams` adds service-defined sign-in parameters; a declared `authorizationUrl`
+ * keeps its own query. Neither can set host-owned parameters, and each parameter appears once.
+ * `request` says where the projected secret fields may be sent, such as
+ * `({ access_token }) => bearer(access_token)`; it runs once, here.
+ */
+export declare function oauth2(options: OAuth2Config & {
+    readonly request?: RequestPlacements<"access_token">;
+}): OAuth2Method<typeof OAuth2AccessToken>;
 export declare function oauth2<Response extends Schema<unknown, boolean>>(options: OAuth2Config & {
     readonly response: Response;
+    readonly request?: RequestPlacements<FieldNameOf<Response>>;
 }): OAuth2Method<Response>;
 export type { AccountSlots } from "./contracts/app.js";
 export type { AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext, } from "./contracts/context.js";
 export { type App, type AppDefinition, defineApp } from "./implementation/app.js";
+export { event, type EventDeclaration, type EventEmitter } from "./implementation/events.js";
+export type { EmitOptions } from "./contracts/events.js";
 export type { Approval, ApprovalContext, ApprovalDecision } from "./approval.js";
 type AuthorWebhook<Member, Config, State> = Member extends object ? Omit<PromiseMethods<Member>, "config" | "state"> & {
     readonly config: Config;
@@ -56,9 +93,14 @@ export type JsonResponse = PromiseMethods<NativeResponse>;
 export declare const decodeJson: <T>(response: JsonResponse, schema: Schema<T, boolean>) => Promise<T>;
 export { NotImplemented } from "./contracts/app.js";
 export { ElicitationFailed, type FormElicitation, type ElicitationResponse, type Elicit, } from "./contracts/elicitation.js";
-export { table, defineDatabase, type Table, type DatabaseReader, type Database, type DatabaseDefinition, } from "./implementation/storage.js";
-export { id, userId } from "./implementation/schema.js";
-export { query, mutation, withApproval, type Operation, type OperationOptions, } from "./implementation/operations.js";
+export type { Sql, SqlCursor, SqlReader, SqlRow, SqlTransaction, SqlValue, } from "./contracts/sql.js";
+/**
+ * `query(options, run)` declares a read operation. `query(name, value)` inside a method's
+ * `request` places a credential in a query parameter, such as `query("key", key)`.
+ */
+export declare function query(name: string, value: PlacementInput): Placement;
+export declare function query<Input, Output, Context extends NativeAppContext = NativeQueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>): ReturnType<typeof operationQuery<Input, Output, Context>>;
+export { mutation, withApproval, toolAnnotations, type Operation, type OperationOptions, } from "./implementation/operations.js";
 export type { OperationContext } from "./contracts/operations.js";
 export { workflow, type Workflow, type WorkflowDeclaration } from "./implementation/workflows.js";
 export { NonRetryableError, WorkflowFailure, type WorkflowContext, type WorkflowStepContext, type WorkflowStep, type WorkflowStepOptions, type WorkflowDuration, type WorkflowReads, type WorkflowControls, } from "./contracts/workflows.js";

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

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

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

@@ -9,4 +9,4 @@ export { OpenapiError, isOpenapiTextMedia, openapiBinaryResultSchema, OpenapiErr
 export declare const openapiRouter: (options: OpenapiToolsOptions, kinds?: OperationKinds) => Promise<import("./index.js").RouterDeclaration<unknown, unknown>>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";
 export * from "./contracts/openapi-compile.js";
-export { liveOpenapiRouter, type OpenapiSourceOptions } from "./implementation/openapi-source.js";
+export { liveOpenapiRouter, openapiToolNames, type OpenapiSourceOptions, type OpenapiToolNamesOptions, } from "./implementation/openapi-source.js";

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -3,6 +3,6 @@ import { Effect } from "effect";
 /** Classify URLs into a fixed set before attaching attributes; raw paths and query strings are never labels. */
 export declare const recordResponseReady: (path: string | undefined, method: string, status: number, milliseconds: number) => Effect.Effect<void, never, never>;
 /** Fixed failure metadata goes to both local/native logs and the metric registry, even when the remote exporter is down. */
-export declare const recordExportFailure: (path: string, reason?: "transport" | "interrupted" | "partial-success" | "capacity" | "acknowledgement", records?: number) => Effect.Effect<void, never, never>;
+export declare const recordExportFailure: (path: string, reason: "transport" | "interrupted" | "partial-success" | "capacity" | "acknowledgement" | "timeout" | "relay" | "shutdown", records?: number) => Effect.Effect<void, never, never>;
 /** Record provider-owned invocation totals separately from response-ready timing. */
 export declare const recordWorkerMeasurements: (worker: string, outcome: string, cpu: number, wall: number) => Effect.Effect<void, never, never>;

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

@@ -0,0 +1,56 @@
+/**
+ * Who a span's work belongs to, and how a measured span's time divides among them. A span that
+ * starts work for someone other than its caller declares the owner with `ownedBy`; any other span
+ * works for whoever its parent works for. Each instant then belongs to the innermost boundary in
+ * progress, so Executor's work inside an upstream session stays Executor's, and an app's callback
+ * inside Executor's cache stays the app's.
+ *
+ * Workers clocks advance only on I/O, so durations are comparable within one isolate and not across
+ * isolates: each isolate measures its own part, and the spans that already bracket the work define
+ * it, so the accounting and the trace agree.
+ */
+import { Context, Effect, Tracer } from "effect";
+/**
+ * Executor's own work; the app's authored code; waiting on an upstream provider; or waiting on a
+ * person's answer.
+ */
+export type Owner = "executor" | "app" | "upstream" | "person";
+/** The attribute that shows a boundary's owner in the trace; the telemetry tracer sets it. */
+export declare const ownerAttribute = "executor.owner";
+/** The owner a span declared when it started, if it is an ownership boundary. */
+export declare const declaredOwner: (annotations: Context.Context<never>) => Owner | undefined;
+/**
+ * Options for a span whose work belongs to `owner`. Every ownership boundary uses them, at the point
+ * the work starts: provider requests and sessions are the upstream's, Executor's services called by
+ * an app are Executor's, an app's callbacks are the app's, and waiting for an answer is the person's.
+ */
+export declare const ownedBy: (owner: Owner, options?: Tracer.SpanOptionsNoTrace) => Tracer.SpanOptionsNoTrace;
+/** Run `effect` in span `name`, owned by `owner`. */
+export declare const owned: (owner: Owner, name: string, options?: Tracer.SpanOptionsNoTrace) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>;
+/** What a measured span does with its work and its end. */
+export interface SpanMeasure {
+    /** Wraps the work inside the span, for example to observe the spans it opens. */
+    readonly around?: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /** Receives the span's end, before the span ends, to record what it measured on it. */
+    readonly end: (end: bigint, span: Tracer.Span) => void;
+}
+/**
+ * Run `effect` in span `name`, measured by `measure` from the span's own start to its own end, so
+ * the span's duration and the measurement share both boundaries.
+ */
+export declare const measuredSpan: (name: string, options: Tracer.SpanOptionsNoTrace, measure: (start: bigint) => SpanMeasure) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>;
+/**
+ * Divide a window that starts at `origin`, whose own work is `owner`'s, among owners. At each
+ * instant, the work in progress is the innermost span of each branch: a span with no child still
+ * open. Its owner takes the instant. With nothing open inside the window, `owner` takes it. Spans
+ * are counted as they open and end, in constant time each, and only spans still open are kept.
+ */
+export declare const makeOwnershipAccounting: (origin: bigint, owner: Owner) => {
+    /** Run `effect` with the spans it opens observed, including spans it hands to later work. */
+    observe: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /**
+     * Close the window at `end` and return its milliseconds by owner, each instant counted once.
+     * Spans still open count up to `end`; spans that open or end afterwards are ignored.
+     */
+    read: (end: bigint) => Readonly<Record<Owner, number>>;
+};

package/types/telemetry/src/recorded-failure.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Failures as Executor's telemetry records them. Traces and error reports keep an error's text only
+ * when Executor wrote it: a tagged error is recorded by its tag and the fixed sentence it declares
+ * (see `RecordedMessage`), or by its tag alone when it declares none. Its fields, message, stack and
+ * cause are not recorded, so a value an error carries for its caller, an app's text or a service's
+ * reply cannot reach telemetry by an error forgetting to declare. The error itself, and what its
+ * caller receives, are unchanged.
+ */
+import { Cause } from "effect";
+/**
+ * The error a trace or error report records in place of `error`.
+ *
+ * - A tagged error is named by its tag: a field called `name`, such as a requested skill's or an
+ *   app's, replaces the error's own name. Its message is the sentence it declares, or empty. Its
+ *   stack is generated here and names no frames: the error's own stack begins with its message,
+ *   which can span lines that look like frames. Traces still show where it failed through the
+ *   operation's own spans, which Effect appends to a recorded stack.
+ * - Any other value that is not an `Error`, such as a plain object Effect would print as JSON, is
+ *   recorded as `UnrecognizedFailure` with no text.
+ * - An untagged `Error` is a defect or a platform's error: its message and stack come from the
+ *   JavaScript engine or a library and are kept, as they are the only diagnosis of an Executor bug.
+ *   Its cause is recorded by these same rules.
+ */
+export declare const recordedError: (error: unknown) => unknown;
+/**
+ * A failure's cause as traces record it: each failure and defect by `recordedError`. Interruptions
+ * are unchanged, and each reason keeps its annotations, which locate it.
+ */
+export declare const recordedCause: <E>(cause: Cause.Cause<E>) => Cause.Cause<unknown>;

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

@@ -2,11 +2,13 @@
 import { Effect, Schema } from "effect";
 /**
  * Forward app telemetry in the host scope without delaying an app result.
- * One export runs at a time, with at most sixteen pending batches. Overload and
- * shutdown loss are reported through the normal safe export-failure signal.
- * Scope release drains for the same three-second budget as the other exporters.
+ * Batches wait in one queue and a single sender exports everything waiting as one request per
+ * signal, so a burst of finished runs costs a few exports instead of one each. The queue holds at
+ * most eight MiB of payload and one export carries at most four. Overload and shutdown loss are
+ * reported through the normal safe export-failure signal. Scope release drains for the same
+ * three-second budget as the other exporters.
  */
-export declare const makeTelemetryForwarder: Effect.Effect<(batch: TelemetryBatch, traceId: string, build?: string) => Effect.Effect<void, never, never>, never, import("effect/Scope").Scope>;
+export declare const makeTelemetryForwarder: Effect.Effect<(batch: TelemetryBatch, traceId: string, source: TelemetrySource) => Effect.Effect<void, never, never>, never, import("effect/Scope").Scope>;
 /** Untrusted isolate batches are bounded before decoding; no endpoint or credential crosses back. */
 export declare const TelemetryBatch: Schema.Struct<{
     readonly traces: Schema.$Array<Schema.String>;
@@ -23,6 +25,14 @@ export declare const collectTelemetry: <A, E, R>(effect: Effect.Effect<A, E, R>)
         logs: string[];
         dropped: number;
     };
-}, E, Exclude<Exclude<R, import("effect/unstable/observability/OtlpExporter").Flusher>, never>>;
+}, E, Exclude<Exclude<R, import("effect/observability/OtlpExporter").Flusher>, never>>;
+/**
+ * What the host knows about the records' source, from its own invocation rather than the records:
+ * the build that ran and, for an app isolate, the app's opaque ID. Both become resource attributes.
+ */
+export interface TelemetrySource {
+    readonly build?: string | undefined;
+    readonly app?: string | undefined;
+}
 /** Validate isolated records and export only this call's trace, using parent-owned credentials/identity. */
-export declare const forwardTelemetry: (batch: TelemetryBatch, traceId: string | undefined, build: string | undefined, service?: "executor-app" | "executor-web") => Effect.Effect<void, Schema.SchemaError | import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Cause").TimeoutError, never>;
+export declare const forwardTelemetry: (batch: TelemetryBatch, traceId: string | undefined, source: TelemetrySource, service?: "executor-app" | "executor-web") => Effect.Effect<void, Schema.SchemaError | import("effect/http/HttpClientError").HttpClientError | import("effect/Cause").TimeoutError, never>;

package/types/telemetry/src/span-attributes.d.ts

@@ -18,11 +18,27 @@
  *
  * Attributes outside these namespaces are the product's own and pass through.
  */
-import { Layer } from "effect";
+import { Effect, Layer } from "effect";
 /** Every HTTP attribute an exported span may carry. */
 export declare const httpSpanAttributeAllowlist: ReadonlySet<string>;
 /** Record this attribute? HTTP names must be allowlisted; product names pass through. */
 export declare const spanAttributeAllowed: (key: string) => boolean;
+/**
+ * Record the template of a route whose path an app or its caller chose, in place of the router's
+ * wildcard: an app's own page or asset, or an app's outbound request. Its last parameter stands
+ * for the rest of the path. It annotates the current span, so call it from the request's handler.
+ */
+export declare const recordRoute: (template: `/${string}`) => Effect.Effect<void, never, never>;
+/**
+ * A fixed set of endpoint templates served under one wildcard route, such as Better Auth's
+ * endpoints under `/api/auth/*`. `:name` stands for one segment. `record` names the request's
+ * endpoint by its template and leaves the wildcard for any path the set does not hold, so a span
+ * keeps which endpoint ran without any segment the caller chose.
+ */
+export declare const routeTemplates: (templates: Iterable<`/${string}`>) => {
+    match: (path: string) => `/${string}` | undefined;
+    record: (path: string) => Effect.Effect<void, never, never>;
+};
 /** Wrap whichever tracer is already in scope; provide this above the exporter. */
 export declare const spanAttributes: (clock?: "system" | "cloudflare-io", recordAll?: boolean) => Layer.Layer<never>;
 /** Header and URL filtering without making an unsupported claim about the runtime clock. */

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

@@ -1,6 +1,13 @@
 import { Context, Layer } from "effect";
-import { HttpClient } from "effect/unstable/http";
+import { HttpClient, HttpClientError } from "effect/http";
 /** Local collector discovery can resolve its destination when an export runs. */
 export declare const CurrentTelemetryClient: Context.Reference<HttpClient.HttpClient | undefined>;
 /** Telemetry consumers inspect status and headers; release response I/O inside each export scope. */
 export declare const telemetryHttpClient: Layer.Layer<HttpClient.HttpClient, never, never>;
+/**
+ * Resend an export the collector refused for now, as OTLP requires and Effect's own
+ * exporters do: lost connections, 429 and 5xx overload, at most three more times. A
+ * collector shedding load answers 429 or 503 with Retry-After, which sets the wait. A
+ * wait longer than the caller's budget ends with the budget, without sending again.
+ */
+export declare const retryTelemetryExport: (client: HttpClient.HttpClient) => HttpClient.HttpClient.With<HttpClientError.HttpClientError, never>;

package/types/utils/src/api-error.d.ts

@@ -0,0 +1,55 @@
+import { Schema, type Cause } from "effect";
+import "effect/http-api";
+/**
+ * Encode the class's `message` getter as a required wire string. Decoding validates the field,
+ * then omits it, so the class derives its own message from the parsed payload and a supplied
+ * value never replaces it.
+ */
+export declare const MessageField: Schema.decodeTo<Schema.optionalKey<Schema.String>, Schema.String, never, never>;
+/** An expected API error whose response states its cause in a `message` derived from its fields. */
+export interface ApiError extends Cause.YieldableError {
+    readonly _tag: string;
+}
+type Header<Tag extends string> = {
+    readonly tag: Tag;
+    readonly status: number;
+};
+type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Header<Tag> & {
+    readonly fields: Fields & {
+        readonly [Key in "_tag" | "message"]?: never;
+    };
+    /**
+     * The cause, stated for API and agent callers. It is also the error's `message`, which traces
+     * record, so it never includes credentials, upstream response text or submitted values.
+     */
+    readonly message: string | ((fields: Schema.Struct.Type<Fields>) => string);
+    /**
+     * What traces and error reports record beside the tag. A fixed `message` is recorded as is; a
+     * message derived from fields is recorded only through this, from fixed text and closed fields,
+     * never a value the caller chose, an app's text or a service's reply. Without it the error is
+     * recorded by its tag alone.
+     */
+    readonly recorded?: (fields: Schema.Struct.Type<Fields>) => string;
+};
+type ErrorFields<Tag extends string, Fields extends Schema.Struct.Fields> = Omit<Schema.TaggedStruct<Tag, Fields & {
+    readonly message: typeof MessageField;
+}>, "~type.make.in"> & {
+    readonly "~type.make.in": Schema.TaggedStruct<Tag, Fields>["~type.make.in"];
+};
+type ErrorClass<Tag extends string, Fields extends Schema.Struct.Fields> = Schema.Class<Schema.Struct.Type<Fields> & ApiError & {
+    readonly _tag: Tag;
+}, ErrorFields<Tag, Fields>, ApiError>;
+/** Define an error with no payload and a fixed message. Its tag is its public error code. */
+declare function define<const Tag extends string>(definition: Header<Tag> & {
+    readonly message: string;
+}): ErrorClass<Tag, {}>;
+/** Define an error whose message can depend on its parsed fields. */
+declare function define<const Tag extends string, const Fields extends Schema.Struct.Fields>(definition: Definition<Tag, Fields>): ErrorClass<Tag, Fields>;
+/**
+ * Define the schema, constructor and API message of an expected error together. Errors that need
+ * a user-facing title and recovery use `UserFacingError`, which carries the same message field.
+ */
+export declare const ApiError: {
+    define: typeof define;
+};
+export {};

package/types/utils/src/connection-failure.d.ts

@@ -0,0 +1,33 @@
+/** Requests the browser could not complete because no response reached it. */
+import { Cause } from "effect";
+import { HttpClientError } from "effect/http";
+import { UserFacingError } from "./user-facing-error.js";
+/**
+ * Fetch rejects with a `TypeError` when no response arrives: the device is offline, the page
+ * navigated away first, the connection was reset before a response, or the browser blocked the
+ * request. The server may still have completed the request and records its own outcome. Failures Executor constructs itself, such as a batch reply
+ * that ended without an answer, carry no such cause and stay unexpected.
+ */
+export declare const isConnectionFailure: (error: unknown) => error is HttpClientError.HttpClientError;
+/** Typed API clients may surface a lost connection as a failure or, after narrowing, a defect. */
+export declare const hasConnectionFailure: (cause: Cause.Cause<unknown>) => boolean;
+/** The browser could not reach Executor. Nothing on the server needs fixing. */
+export declare const ConnectionFailed: import("effect/Schema").Class<{} & UserFacingError & {
+    readonly _tag: "ConnectionFailed";
+}, Omit<import("effect/Schema").TaggedStruct<"ConnectionFailed", {
+    readonly message: typeof import("./api-error.js").MessageField;
+    readonly recovery: import("effect/Schema").decodeTo<import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+        readonly action: import("effect/Schema").String;
+        readonly instructions: import("effect/Schema").String;
+    }>>, import("effect/Schema").Struct<{
+        readonly action: import("effect/Schema").String;
+        readonly instructions: import("effect/Schema").String;
+    }>, never, never>;
+}>, "~type.make.in"> & {
+    readonly "~type.make.in": {
+        readonly _tag?: "ConnectionFailed";
+    };
+}, UserFacingError>;
+export type ConnectionFailed = typeof ConnectionFailed.Type;
+/** What to show for a failure no contract declares: a lost connection, or an unexpected error. */
+export declare const undeclaredError: (cause: Cause.Cause<unknown>) => UserFacingError;