apps 0.0.1-beta.43 → 0.0.1-beta.46

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

@@ -119,6 +119,21 @@ export declare const HostDataError: Schema.Union<readonly [typeof OpenapiRespons
 export declare const ToolResultObservation: Context.Reference<{
     readonly failed: () => void;
 }>;
+/**
+ * One tool invocation's own timing, on the isolate's clock: how long it ran, and how much of that
+ * it waited on upstream providers, waited on elicitation answers and ran the app's authored code.
+ * Each instant counts once, so the rest is Executor's own time. The isolated handler returns it
+ * beside the result so the host can add the other isolates' parts.
+ */
+export declare const InvocationTiming: Schema.Struct<{
+    readonly elapsedMs: Schema.Finite;
+    readonly upstreamMs: Schema.Finite;
+    readonly elicitationMs: Schema.Finite;
+    readonly authoredMs: Schema.Finite;
+}>;
+export type InvocationTiming = typeof InvocationTiming.Type;
+/** Receives the invocation's timing once it is over; hosts that do not return it ignore it. */
+export declare const InvocationTimingSink: Context.Reference<(timing: InvocationTiming) => void>;
 /** Native handler; context comes from host authority, never from request content. */
 export type AppHandler = (request: Request, context: HostContext) => Effect.Effect<Response>;
 export { type AppOperation, type OperationContext } from "./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/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/cache.d.ts

@@ -1,8 +1,12 @@
+/** Bind the portable Effect cache to an app invocation's author API. */
+import { type Context } from "effect";
 import type { AppCache, HostCache } from "../contracts/cache.js";
 import type { ResolvedAccounts } from "../contracts/host.js";
 /** Missing host support is explicit on use; ordinary apps do not need cache support. */
 export declare const unavailableCache: HostCache;
 /** Account scopes are derived from trusted current bindings. Loaders get a fresh owned HTTP signal. */
 export declare const authorCache: (host: HostCache, accounts: ResolvedAccounts, signal: AbortSignal, 
+/** The invocation's telemetry, which Promise calls from authored code run in. */
+telemetry: Context.Context<never>, 
 /** The invocation's trusted deadline. Waiting on another caller's load never runs past it. */
 deadline?: number) => AppCache;

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

@@ -1,5 +1,5 @@
 /** Validate both sides of a tool's form and bind delivery to its invocation lifetime. */
-import { Effect, Schema } from "effect";
+import { Effect, Schema, type Context } from "effect";
 import { ElicitationFailed, type ElicitationHandler, type Elicit } from "../contracts/elicitation.js";
 /** Parse a form and retain its response parser, so invalid answers can be rejected before consuming a host continuation. */
 export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
@@ -99,5 +99,8 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
         } | undefined;
     }, ElicitationFailed, never>;
 }, ElicitationFailed, never>;
-/** Bind a validated interaction to the live invocation; transport adapters share its form parser. */
-export declare const makeElicit: (handler: ElicitationHandler | undefined, signal: AbortSignal) => Elicit;
+/**
+ * Bind a validated interaction to the live invocation; transport adapters share its form parser.
+ * Authored code's Promise calls run in the invocation's telemetry, like framework callers.
+ */
+export declare const makeElicit: (handler: ElicitationHandler | undefined, signal: AbortSignal, telemetry: Context.Context<never>) => Elicit;

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

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

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

@@ -1,5 +1,5 @@
 /** Pure operation declarations. Only the author callback crosses the Promise boundary. */
-import { Effect, Schema as EffectSchema } from "effect";
+import { Schema as EffectSchema } from "effect";
 import type { AppOperation } from "../contracts/operations.js";
 import type { AppContext, QueryContext, MutationContext } from "../contracts/context.js";
 import type { Approval } from "../approval.js";
@@ -64,7 +64,7 @@ export interface OperationOptions<Input, Output> {
 }
 /** Adapt metadata and approval without running user code. */
 export declare const operationOptions: <Input, Output>(options: OperationOptions<Input, Output>) => {
-    approval?: (context: Parameters<Approval<Input>>[0]) => Effect.Effect<"approved" | "denied" | "user-approval", unknown, never>;
+    approval?: (context: Parameters<Approval<Input>>[0]) => import("effect/Effect").Effect<"approved" | "denied" | "user-approval", unknown, never>;
     input: EffectSchema.Decoder<Input, never>;
     _meta?: {
         readonly [x: string]: EffectSchema.Json;

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

@@ -29,6 +29,7 @@ export declare const routerSkillName: (path: string) => string;
 export declare const operationSummary: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
     readonly description: string;
     readonly name: string;
+    readonly router?: string;
     readonly title?: string;
     readonly annotations?: {
         readonly title?: string;
@@ -52,7 +53,6 @@ export declare const operationSummary: (name: string, router: string, operation:
         readonly input: Schema.Json;
     }[];
     readonly readOnly?: boolean;
-    readonly router?: string;
     readonly tags?: readonly string[];
 }, HostDeclarationInvalid, never>;
 /** A declared operation's full description, including rendered schemas. */
@@ -65,6 +65,7 @@ export declare const operationDescription: (name: string, router: string, operat
     readonly _meta?: {
         readonly [x: string]: Schema.Json;
     };
+    readonly router?: string;
     readonly title?: string;
     readonly annotations?: {
         readonly title?: string;
@@ -91,7 +92,6 @@ export declare const operationDescription: (name: string, router: string, operat
         readonly input: Schema.Json;
     }[];
     readonly readOnly?: boolean;
-    readonly router?: string;
     readonly tags?: readonly string[];
 }, HostDeclarationInvalid, never>;
 /**
@@ -128,6 +128,7 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
         readonly _meta?: {
             readonly [x: string]: Schema.Json;
         };
+        readonly router?: string;
         readonly title?: string;
         readonly annotations?: {
             readonly title?: string;
@@ -154,11 +155,11 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
             readonly input: Schema.Json;
         }[];
         readonly readOnly?: boolean;
-        readonly router?: string;
         readonly tags?: readonly string[];
     } | {
         readonly description: string;
         readonly name: string;
+        readonly router?: string;
         readonly title?: string;
         readonly annotations?: {
             readonly title?: string;
@@ -182,7 +183,6 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
             readonly input: Schema.Json;
         }[];
         readonly readOnly?: boolean;
-        readonly router?: string;
         readonly tags?: readonly string[];
     })[];
     routers: {

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

@@ -1,5 +1,5 @@
 /** Ordinary async workflow declarations, adapted once into native Effect handlers. */
-import { type Schema as EffectSchema } from "effect";
+import type { Schema as EffectSchema } from "effect";
 import type { AppWorkflow, WorkflowContext } from "../contracts/workflows.js";
 import { type Schema } from "./schema.js";
 declare const NativeWorkflow: unique symbol;

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

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

package/types/telemetry/src/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

@@ -1,20 +1,29 @@
 /**
- * Failures as Executor's telemetry records them. An error whose message can carry an app's own
- * text declares a fixed sentence instead (see `RecordedMessage`); traces and error reports record
- * that sentence with the error's name. The error itself, and what its caller receives, are
- * unchanged.
+ * 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`. 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, so none of its text is kept. Traces still show where it failed through the
- * operation's own spans, which Effect appends to a recorded stack.
+ * 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. A defect is recorded the same way when it is an error that
- * declares a recorded message, such as a workflow failure a host turned into a defect; other
- * defects and interruptions are unchanged. Each reason keeps its annotations, which locate it.
+ * 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/utils/src/api-error.d.ts

@@ -24,8 +24,10 @@ type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Heade
      */
     readonly message: string | ((fields: Schema.Struct.Type<Fields>) => string);
     /**
-     * What traces and error reports record instead of `message`, when the message quotes an app's
-     * own error or a service's stated error for its caller. Only fixed text and typed fields.
+     * 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;
 };

package/types/utils/src/recorded-message.d.ts

@@ -1,8 +1,11 @@
 /**
- * What traces and error reports record for an error in place of its message. An error declares
- * one when its message can carry text from outside Executor: an app's own error or output, or an
- * error a service stated through an app. That text still reaches the caller the error is for;
- * Executor's telemetry records only this fixed sentence, beside the error's name.
+ * The fixed sentence traces and error reports record for a tagged error, beside its tag. Telemetry
+ * records no other text from a tagged error: one that declares no sentence is recorded by its tag
+ * alone (`@executor-js/telemetry/recorded-failure`). Declare one from fixed text and closed fields
+ * only, never from a value the caller supplied (a slug, a name, a tool name, an argument's key),
+ * an app's own text or a service's reply. That text still reaches the caller the error is for.
+ * `ApiError` and `UserFacingError` declare a fixed message for you; a message derived from fields
+ * declares `recorded`.
  */
 export declare const RecordedMessage: unique symbol;
 /** The fixed sentence an error declares for telemetry, if it declares one. */

package/types/utils/src/user-facing-error.d.ts

@@ -43,8 +43,10 @@ type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Heade
         readonly [Key in keyof PresentationProperties | "_tag" | "message"]?: never;
     };
     /**
-     * What traces and error reports record instead of the description, when the description quotes
-     * an app's own error or a service's stated error for its caller. Only fixed text and typed fields.
+     * What traces and error reports record beside the tag. A fixed description is recorded as is; a
+     * presentation 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;
 } & (ErrorPresentation | {

package/js/chunk-EG72MSVK.js

@@ -1,16 +0,0 @@
-import {
-  Predicate_exports
-} from "./chunk-IFJU5SYQ.js";
-
-// ../utils/src/recorded-message.ts
-var RecordedMessage = /* @__PURE__ */ Symbol.for("@executor-js/utils/RecordedMessage");
-var recordedMessage = (error) => {
-  if (!Predicate_exports.hasProperty(error, RecordedMessage)) return void 0;
-  const message = error[RecordedMessage];
-  return typeof message === "string" ? message : void 0;
-};
-
-export {
-  RecordedMessage,
-  recordedMessage
-};

package/js/{chunk-LNSVJS2Q.js → chunk-EOPQ727L.js}

@@ -4392,8 +4392,6 @@ export {
   bodyFormData,
   HttpClientRequest_exports,
   fromWeb2 as fromWeb,
-  HttpServerResponse_exports,
-  HttpServerRequest_exports,
   HttpTraceContext_exports,
   HttpClient,
   transformResponse,
@@ -4406,6 +4404,8 @@ export {
   TracerPropagationEnabled,
   layerMergedContext,
   HttpClient_exports,
+  HttpServerResponse_exports,
+  HttpServerRequest_exports,
   prefixPath,
   fromLiteral
 };