apps 0.0.1-beta.0 → 0.0.1-beta.10

package/types/apps/src/implementation/openapi-request.d.ts

@@ -1,11 +1,17 @@
-/** HTTP serialization for normalized OpenAPI operations. */
+import { ProviderError } from "../contracts/provider-error.js";
+/** Swagger constructs requests; Effect owns HTTP policy and bounded results. */
 import { Effect, Schema } from "effect";
-import { OpenapiError, type CredentialBinding, type OpenapiOperation, type OpenapiAccount } from "../contracts/openapi.js";
+import { OpenapiResponseError } from "../contracts/api-response-error.js";
+import { OpenapiError, type CredentialBinding, type OpenapiOperation, type OpenapiAccount, type OpenapiErrorResponse } from "../contracts/openapi.js";
+type DeclaredError = OpenapiErrorResponse & {
+    readonly decoder: Schema.Decoder<Schema.Json>;
+};
 /** Create request helpers from credential-free generated authentication metadata. */
 export declare function createRequest(config: {
     readonly methods: Readonly<Record<string, readonly CredentialBinding[]>>;
     readonly oauth: readonly string[];
 }): {
-    available: (op: OpenapiOperation, method: string | undefined) => boolean;
-    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined) => Effect.Effect<Schema.Json, OpenapiError, never>;
+    available: (op: OpenapiOperation, account: OpenapiAccount | undefined) => boolean;
+    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | OpenapiResponseError | OpenapiError, never>;
 };
+export {};

package/types/apps/src/implementation/openapi-source.d.ts

@@ -0,0 +1,36 @@
+/** Revisioned OpenAPI sources. Calls read a manifest, one operation and only its schema dependencies. */
+import { Duration } from "effect";
+import type { AppCache } from "../contracts/cache.js";
+import { OpenapiOperation, type OpenapiToolsOptions } from "../contracts/openapi.js";
+import { JsonObject, JsonValue } from "../contracts/schema.js";
+import { type OperationKinds } from "./protocol-operations.js";
+import { type RouterDeclaration } from "./router.js";
+/** Static credential placement and destination are reviewed when the app is authored/imported. */
+export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operations" | "definitions"> {
+    readonly cache: AppCache;
+    readonly source: {
+        readonly url: string;
+    } | {
+        readonly document: JsonObject;
+    };
+    readonly allowedOrigin: string;
+    readonly securitySchemes: Readonly<Record<string, JsonObject>>;
+    readonly baseUrl?: string;
+    readonly freshFor?: Duration.Input;
+    readonly staleFor?: Duration.Input;
+    /**
+     * Query or mutation overrides keyed by the document's operationId. An operation without an
+     * operationId is keyed by its generated name without the kind, such as `users.getUsers`.
+     */
+    readonly kinds?: OperationKinds;
+    readonly fallbackSecurity?: OpenapiOperation["request"]["security"];
+    readonly patches?: readonly {
+        readonly op: "add" | "remove" | "replace";
+        readonly path: string;
+        readonly value?: JsonValue;
+    }[];
+}
+/** JSON-object patches are static app configuration and are reapplied to every revision. */
+export declare function patchOpenapi(root: JsonObject, patches: OpenapiSourceOptions["patches"]): JsonObject;
+/** No I/O during app construction. All accounts share credential-free compilation. */
+export declare const liveOpenapiRouter: (options: OpenapiSourceOptions) => RouterDeclaration;

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

@@ -1,5 +1,41 @@
 /** Evaluate normalized metadata into ordinary tools, with account-specific security filtering. */
-import { Effect } from "effect";
-import { OpenapiError, OpenapiToolsOptions, type OpenapiTools } from "../contracts/openapi.js";
+import { Effect, Schema } from "effect";
+import { OpenapiError, OpenapiToolsOptions, type OpenapiTools, type OpenapiOperation, type OpenapiParameterDefaults } from "../contracts/openapi.js";
+import type { JsonObject, JsonValue } from "../contracts/schema.js";
+/** Names of shared definitions a JSON value references directly as `#/$defs/<name>`. */
+export declare function references(value: JsonValue, found?: Set<string>): Set<string>;
+/**
+ * Make a schema self-contained with only the shared definitions it reaches. Cycles stay
+ * references to the same definition. A missing definition stays unresolved and fails when
+ * the schema compiles. The schema's own `$defs` keep precedence.
+ */
+export declare const bundler: (definitions: Readonly<Record<string, JsonObject>>) => (schema: JsonObject) => JsonObject;
+/**
+ * Make account-bound parameters optional. Validators omit the values so they stay account-free;
+ * the published schema includes them as `default` so callers can see what an omission sends.
+ */
+export declare const parameterDefaultsInput: (op: OpenapiOperation, defaults: OpenapiParameterDefaults | undefined, publish: boolean) => JsonObject;
+/** Account-free validators can be reused inside a Worker for one immutable revision. */
+export declare const prepareOpenapiOperation: (op: OpenapiOperation, definitions: Readonly<Record<string, JsonObject>>, defaults?: OpenapiParameterDefaults) => Effect.Effect<{
+    input: Schema.declareConstructor<Schema.Json, Schema.Json, readonly [], Schema.Json>;
+    errors: {
+        decoder: Schema.declareConstructor<Schema.Json, Schema.Json, readonly [], Schema.Json>;
+        code: string;
+        status: number;
+        message: {
+            readonly source: "body";
+        } | {
+            readonly source: "schema";
+            readonly value: string;
+        };
+        schema: {
+            readonly [x: string]: Schema.Json;
+        };
+    }[];
+    output: () => {
+        readonly [x: string]: Schema.Json;
+    } | undefined;
+}, never, never>;
+export type PreparedOpenapiOperation = Effect.Success<ReturnType<typeof prepareOpenapiOperation>>;
 /** Decode retained metadata and expose only operations supported by the selected account. */
-export declare const openapiToolsEffect: (options: OpenapiToolsOptions) => Effect.Effect<OpenapiTools, OpenapiError>;
+export declare const openapiToolsEffect: (options: OpenapiToolsOptions, prepared?: ReadonlyMap<string, PreparedOpenapiOperation>) => Effect.Effect<OpenapiTools, OpenapiError>;

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

@@ -7,16 +7,39 @@ import type { ToolAnnotations } from "../contracts/tools.js";
 import type { JsonObject } from "../contracts/schema.js";
 import { type Schema } from "./schema.js";
 declare const NativeOperation: unique symbol;
-declare const HandlerContext: unique symbol;
-/** A server-only declaration with its category preserved for catalog validation. */
+declare const QueryHandlerContext: unique symbol;
+declare const MutationHandlerContext: unique symbol;
+/**
+ * A server-only declaration with its category preserved for catalog validation. Queries and
+ * mutations carry their handler context under different phantom keys, so a router can type a
+ * query's handler from its query context alone.
+ */
 export interface OperationDeclaration<Kind extends "query" | "mutation", Context = never> {
-    readonly [HandlerContext]?: (context: Context) => void;
+    readonly [QueryHandlerContext]?: "query" extends Kind ? (context: Context) => void : never;
+    readonly [MutationHandlerContext]?: "mutation" extends Kind ? (context: Context) => void : never;
     readonly kind: Kind;
     readonly [NativeOperation]: Omit<AppOperation<never>, "kind" | "input"> & {
         readonly kind: Kind;
         readonly input: EffectSchema.Decoder<unknown>;
     };
 }
+/**
+ * A router declaration. The phantom contexts let `defineApp` type inline handlers; protocol
+ * routers accept any context because their operations only use the framework's own capabilities.
+ * The native router is held under a private key in implementation/router.ts.
+ */
+export interface RouterDeclaration<Query = unknown, Mutation = unknown> {
+    readonly [QueryHandlerContext]?: (context: Query) => void;
+    readonly [MutationHandlerContext]?: (context: Mutation) => void;
+    readonly [NativeRouterKey]: unknown;
+}
+/** An operation or nested router under one key. Each child is typed only by its own kind's context. */
+export interface RouterChild<Query, Mutation> {
+    readonly [QueryHandlerContext]?: (context: Query) => void;
+    readonly [MutationHandlerContext]?: (context: Mutation) => void;
+}
+/** Private key for a router's native definition. */
+export declare const NativeRouterKey: unique symbol;
 /** Typed operation handles drive browser reference inference without bundling handlers. */
 export interface Operation<Input, Output, Kind extends "query" | "mutation", Context = AppContext> extends OperationDeclaration<Kind, Context> {
     readonly [NativeOperation]: AppOperation<Input, Output> & {

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

@@ -17,8 +17,7 @@ interface ProtocolOperation {
     readonly run: (context: OperationContext, input: JsonValue) => Effect.Effect<unknown, unknown>;
 }
 /** Unknown behavior defaults to mutation. Classification never enforces an external service's behavior. */
-export declare const protocolOperations: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => {
-    queries: Record<string, Operation<Schema.Json, unknown, "query", OperationContext>>;
-    mutations: Record<string, Operation<Schema.Json, unknown, "mutation", OperationContext>>;
-};
+export declare const protocolOperations: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => Record<string, Operation<Schema.Json, unknown, "query" | "mutation", OperationContext>>;
+/** Operations already discovered, as a router keyed by upstream name. */
+export declare const protocolRouter: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => import("./operations.js").RouterDeclaration<unknown, unknown>;
 export {};

package/types/apps/src/implementation/provider-error.d.ts

@@ -0,0 +1,10 @@
+import { Option } from "effect";
+import { ProviderError } from "../contracts/provider-error.js";
+/** Parse and rebuild the allowlisted fields, including when the input is already an Error instance. */
+export declare function parseProviderError(error: unknown): Option.Option<ProviderError>;
+/** Classify only explicit HTTP evidence. Raw provider content never enters the error. */
+export declare function httpProviderError(status: number, headers?: Readonly<Record<string, string>>): ProviderError | undefined;
+/** Attach the account used by the enclosing operation, without preserving arbitrary thrown fields. */
+export declare function accountProviderError<E>(error: E, accountId: string): E | ProviderError;
+/** GraphQL has no standard auth code; recognize these documented codes without guessing from prose. */
+export declare function graphqlProviderError(errors: readonly unknown[], status: number): ProviderError | undefined;

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

@@ -1,6 +1,7 @@
 /** Pure constructors over the native provider contracts. */
 import { Effect, Schema } from "effect";
-import { type AuthMethods, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import { type PromiseMethod } from "./authoring.js";
+import { type AccountCheck, type AuthMethods, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
 import type { ValidationError } from "../contracts/schema.js";
 /** Declare a secrets method with an Effect decoder. */
 export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options: {
@@ -9,8 +10,12 @@ export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options:
 }) => SecretsMethod<Fields>;
 /** Validate OAuth endpoints while declaring their app-visible response projection. */
 export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
-/** Retain the provider and literal method names without registering or authenticating it. */
-export declare const defineProvider: <const Auth extends AuthMethods>(options: {
+/** Author options: the account check is an ordinary async function. */
+export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
     readonly auth: Auth;
-}) => Provider<Auth>;
+    /** Verify a connected account with a safe read, optionally reporting its upstream identity. */
+    readonly health?: PromiseMethod<AccountCheck<Auth>["run"]>;
+}
+/** Retain the provider and literal method names without registering or authenticating it. */
+export declare const defineProvider: <const Auth extends AuthMethods>({ health, ...options }: ProviderOptions<Auth>) => Provider<Auth>;

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

@@ -0,0 +1,225 @@
+/**
+ * Read a live router tree into tools, routers and router skills. A nested dynamic router that fails
+ * is reported on its own entry; the root failing fails the read, as a single-source app would.
+ */
+import { Effect, Schema } from "effect";
+import { HostDeclarationInvalid, HostEvaluationFailed, type HostRouterError } from "../contracts/host.js";
+import { McpError } from "../contracts/mcp.js";
+import type { AppOperation } from "../contracts/operations.js";
+import type { AppRouter, DynamicRouter, RouterMeta } from "../contracts/router.js";
+import { SkillLoadFailed } from "../contracts/skills.js";
+import type { OperationSchedule } from "../contracts/schedules.js";
+/**
+ * Keep only a failure's safe fields. Anything unrecognized becomes an evaluation failure with the
+ * error's name and bounded message, with the given account secrets replaced.
+ */
+export declare const safeFailure: (error: unknown, secrets: readonly string[]) => HostRouterError;
+/**
+ * Router skills are named `tools` for the root and `tools-<path>` below it, so a router's
+ * instructions never take an authored skill's name by accident.
+ */
+export declare const routerSkillPrefix = "tools";
+/**
+ * The skill name for a router path. A path of lowercase letters and digits is spelled out:
+ * `issues.open` is `tools-issues-open`. Any other path, or one too long, is a readable slug
+ * followed by a hash of the exact path, such as `tools-issues-list-0123456789`. Plain segments
+ * start with a letter and a hash is all digits, so the two forms never meet, and paths that slug
+ * alike, such as `issues_list` and `issues.list`, get different names.
+ */
+export declare const routerSkillName: (path: string) => string;
+/** A declared operation's catalog entry without schemas. `router` is its owning router's path. */
+export declare const operationSummary: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
+    readonly name: string;
+    readonly description: string;
+    readonly title?: string;
+    readonly annotations?: {
+        readonly title?: string;
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly idempotentHint?: boolean;
+        readonly openWorldHint?: boolean;
+    };
+    readonly schedules?: readonly {
+        readonly name: string;
+        readonly timing: {
+            readonly kind: "interval";
+            readonly milliseconds: number;
+        } | {
+            readonly kind: "cron";
+            readonly calendar: {
+                readonly expression: string;
+                readonly timezone: string;
+            };
+        };
+        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. */
+export declare const operationDescription: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly _meta?: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly title?: string;
+    readonly annotations?: {
+        readonly title?: string;
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly idempotentHint?: boolean;
+        readonly openWorldHint?: boolean;
+    };
+    readonly outputSchema?: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly schedules?: readonly {
+        readonly name: string;
+        readonly timing: {
+            readonly kind: "interval";
+            readonly milliseconds: number;
+        } | {
+            readonly kind: "cron";
+            readonly calendar: {
+                readonly expression: string;
+                readonly timezone: string;
+            };
+        };
+        readonly input: Schema.Json;
+    }[];
+    readonly readOnly?: boolean;
+    readonly router?: string;
+    readonly tags?: readonly string[];
+}, HostDeclarationInvalid, never>;
+/**
+ * A dynamic router over operations already discovered, such as an eager OpenAPI document or a
+ * stdio server. Upstream names can contain dots, which static router keys cannot.
+ */
+export declare const fixedRouter: (operations: Readonly<Record<string, AppOperation>>, meta?: RouterMeta) => DynamicRouter;
+export interface CatalogOptions {
+    /** Omit schemas. */
+    readonly summary: boolean;
+    /** Account secrets that a failure's message must not reveal. */
+    readonly secrets: readonly string[];
+    /** Only these full tool names. Routers with none of them are not read. */
+    readonly wanted?: ReadonlySet<string>;
+    /** Schedules that target a declared operation, by full name. */
+    readonly schedules: (name: string) => readonly OperationSchedule[];
+    /**
+     * Only declared operations that have schedules. Schedules never target dynamic routers, and
+     * their catalogs can be expensive to discover, so none is read.
+     */
+    readonly scheduled?: true;
+}
+/**
+ * Read a router tree. Every nested router is listed, for grouping; the root only when it has
+ * metadata. A nested dynamic source that fails is reported on its router's entry.
+ */
+export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined, options: CatalogOptions) => Effect.Effect<{
+    tools: ({
+        readonly name: string;
+        readonly description: string;
+        readonly inputSchema: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly _meta?: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly title?: string;
+        readonly annotations?: {
+            readonly title?: string;
+            readonly readOnlyHint?: boolean;
+            readonly destructiveHint?: boolean;
+            readonly idempotentHint?: boolean;
+            readonly openWorldHint?: boolean;
+        };
+        readonly outputSchema?: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly schedules?: readonly {
+            readonly name: string;
+            readonly timing: {
+                readonly kind: "interval";
+                readonly milliseconds: number;
+            } | {
+                readonly kind: "cron";
+                readonly calendar: {
+                    readonly expression: string;
+                    readonly timezone: string;
+                };
+            };
+            readonly input: Schema.Json;
+        }[];
+        readonly readOnly?: boolean;
+        readonly router?: string;
+        readonly tags?: readonly string[];
+    } | {
+        readonly name: string;
+        readonly description: string;
+        readonly title?: string;
+        readonly annotations?: {
+            readonly title?: string;
+            readonly readOnlyHint?: boolean;
+            readonly destructiveHint?: boolean;
+            readonly idempotentHint?: boolean;
+            readonly openWorldHint?: boolean;
+        };
+        readonly schedules?: readonly {
+            readonly name: string;
+            readonly timing: {
+                readonly kind: "interval";
+                readonly milliseconds: number;
+            } | {
+                readonly kind: "cron";
+                readonly calendar: {
+                    readonly expression: string;
+                    readonly timezone: string;
+                };
+            };
+            readonly input: Schema.Json;
+        }[];
+        readonly readOnly?: boolean;
+        readonly router?: string;
+        readonly tags?: readonly string[];
+    })[];
+    routers: {
+        readonly path: string;
+        readonly error?: import("../index.js").ProviderError | SkillLoadFailed | McpError | HostDeclarationInvalid | HostEvaluationFailed;
+        readonly description?: string;
+        readonly title?: string;
+        readonly tags?: {
+            readonly [x: string]: string;
+        };
+        readonly icons?: readonly {
+            readonly src: string;
+            readonly mimeType?: string;
+            readonly sizes?: readonly string[];
+            readonly theme?: "light" | "dark";
+        }[];
+        readonly skill?: string;
+    }[];
+}, import("../index.js").ProviderError | SkillLoadFailed | McpError | HostDeclarationInvalid | HostEvaluationFailed, never>;
+/**
+ * One skill for each router with instructions. Skills and tools fail independently: a dynamic
+ * router whose metadata cannot be read, including the root, contributes no skill and does not
+ * fail the others. Metadata comes through each source's catalog cache, like a tool listing.
+ */
+export declare const routerSkills: (root: AppRouter | DynamicRouter | undefined) => Effect.Effect<{
+    readonly name: string;
+    readonly description: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly license?: string;
+    readonly compatibility?: string;
+    readonly metadata?: {
+        readonly [x: string]: string;
+    };
+    readonly "allowed-tools"?: string;
+}[], never, never>;

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

@@ -0,0 +1,59 @@
+import { HostedTool } from "../contracts/host.js";
+import type { AppOperation } from "../contracts/operations.js";
+import { RouterMeta, type AppRouter, type DynamicRouter, type RouterIcon } from "../contracts/router.js";
+import { type OperationDeclaration, type RouterChild, type RouterDeclaration } from "./operations.js";
+export type { RouterChild, RouterDeclaration } from "./operations.js";
+/** Author metadata for a router. Instructions become a skill named after the router's path. */
+export interface RouterOptions {
+    readonly title?: string;
+    readonly description?: string;
+    readonly instructions?: string;
+    readonly icons?: readonly RouterIcon[];
+    readonly tags?: Readonly<Record<string, string>>;
+}
+/** Wrap a native router. Protocol helpers use this for the routers they build. */
+export declare const routerDeclaration: (node: AppRouter | DynamicRouter) => RouterDeclaration;
+/** Accept only framework-created routers. */
+export declare const nativeRouter: (value: unknown) => AppRouter | DynamicRouter | undefined;
+/** Author fields win; a field the author omits keeps the source's value. */
+export declare const mergeMeta: (base: RouterMeta | undefined, override: RouterMeta | undefined) => RouterMeta | undefined;
+/**
+ * Group operations and routers under path keys, like tRPC's nested routers, with metadata an
+ * agent can read. Passing an existing router instead of children overrides its metadata:
+ * `router(mcpRouter(options), { description: "..." })`.
+ */
+export declare function router<Query = unknown, Mutation = unknown>(children: Readonly<Record<string, RouterChild<Query, Mutation>>>, options?: RouterOptions): RouterDeclaration<Query, Mutation>;
+export declare function router<Query, Mutation>(source: RouterDeclaration<Query, Mutation>, options: RouterOptions): RouterDeclaration<Query, Mutation>;
+/**
+ * Declare a router whose tools are discovered when read. `list` returns tools with names relative
+ * to this router; mark queries with `readOnly: true`. `resolve` receives one of those names.
+ */
+export declare const dynamicRouter: (source: {
+    readonly meta?: () => RouterOptions | Promise<RouterOptions>;
+    readonly list: () => readonly HostedTool[] | Promise<readonly HostedTool[]>;
+    readonly resolve: (name: string) => OperationDeclaration<"query" | "mutation", unknown> | undefined | Promise<OperationDeclaration<"query" | "mutation", unknown> | undefined>;
+}) => RouterDeclaration;
+/** Join a router path and a relative name. The root router's path is "". */
+export declare const joinPath: (path: string, name: string) => string;
+/** Where a full tool name points: a declared operation, or a name inside a dynamic router. */
+export type Location = {
+    readonly kind: "operation";
+    readonly operation: AppOperation;
+    readonly router: string;
+} | {
+    readonly kind: "dynamic";
+    readonly source: DynamicRouter;
+    readonly router: string;
+    readonly name: string;
+};
+/**
+ * Walk static keys until the name ends at an operation or enters a dynamic router, which receives
+ * the rest of the name. Static keys contain no dots, so every name has at most one location.
+ */
+export declare const locate: (root: AppRouter | DynamicRouter | undefined, name: string) => Location | undefined;
+/** Every declared operation with its full name and owning router. Dynamic routers are not listed. */
+export declare const declaredOperations: (root: AppRouter | undefined, path?: string) => Array<{
+    readonly name: string;
+    readonly router: string;
+    readonly operation: AppOperation;
+}>;

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

@@ -1,6 +1,6 @@
 /** Author schema facade. Internals use the native decoder retained by each value. */
 import { Effect, Schema as EffectSchema } from "effect";
-import { ValidationError, type JsonObject } from "../contracts/schema.js";
+import { JsonObject, ValidationError } from "../contracts/schema.js";
 import type { Field } from "../../../app-data/src/contracts/database.js";
 declare const StorageField: unique symbol;
 declare const Decoder: unique symbol;
@@ -64,6 +64,10 @@ declare const ImportedJsonSchema: unique symbol;
 export declare const importedJsonSchema: (decoder: EffectSchema.Decoder<unknown>) => unknown | undefined;
 /** Attach a composed discovery document without replacing its authoritative native decoder. */
 export declare const withJsonSchemaDocument: <S extends EffectSchema.Decoder<unknown>>(decoder: S, document: JsonObject) => S;
+/** Compute a value on first use and reuse it. */
+export declare const once: <A>(compute: () => A) => (() => A);
+/** Attach a discovery document that is built only when it is first read. */
+export declare const withLazyJsonSchemaDocument: <S extends EffectSchema.Decoder<unknown>>(decoder: S, document: () => JsonObject) => S;
 /**
  * Relocate a self-contained JSON Schema under a document pointer. Resolve references
  * before nesting so account schemas can reuse definition names, IDs and anchors.
@@ -76,12 +80,9 @@ export declare const compileJsonSchemaDecoder: (document: JsonObject) => Effect.
         readonly [x: string]: EffectSchema.Json;
     };
 }, ValidationError, never>;
+export declare const lazyJsonSchemaDecoder: (document: () => JsonObject) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>, never, never>;
 /** Preserve the JSON document; compile its validator only when a value is first decoded. */
-export declare const jsonSchemaDecoder: (input: unknown) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json> & {
-    [ImportedJsonSchema]: {
-        readonly [x: string]: EffectSchema.Json;
-    };
-}, ValidationError, never>;
+export declare const jsonSchemaDecoder: (input: unknown) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>, ValidationError, never>;
 /** Import JSON metadata now; unsupported schemas and invalid values fail when parsed. */
 export declare const jsonSchema: (input: unknown) => Schema<EffectSchema.Json>;
 /** Database declaration retained by primitive constructors; nested payload schemas are not database fields. */
@@ -90,4 +91,8 @@ export declare const storageFieldOf: (schema: Schema<unknown, boolean>) => Field
 export declare const id: (table: string) => Schema<string>;
 /** A host user identifier, stored as a string without imposing a product auth model. */
 export declare const userId: () => Schema<string>;
+/** Render a decoder as a JSON Schema document, keeping an imported upstream document as-is. */
+export declare const jsonSchemaDocument: (decoder: EffectSchema.Decoder<unknown>) => Effect.Effect<{
+    readonly [x: string]: EffectSchema.Json;
+}, EffectSchema.SchemaError, never>;
 export {};

package/types/apps/src/implementation/skill-files.d.ts

@@ -0,0 +1,10 @@
+/** One parser for packaged, GitHub and well-known skill files. */
+import { Effect } from "effect";
+import { AppSkillSource, SkillDefinitionInvalid, SkillFile, type FolderSkillsOptions } from "../contracts/skills.js";
+/** Parse one skill directory, retaining its full document and validating an optional source name. */
+export declare const skillFromFiles: (input: readonly SkillFile[], source?: {
+    readonly directory?: string;
+    readonly name?: string;
+}) => Effect.Effect<AppSkillSource, SkillDefinitionInvalid>;
+/** Select immediate skill directories from packaged text files. Never accesses the host filesystem. */
+export declare const folderSkillsEffect: (options: FolderSkillsOptions) => Effect.Effect<readonly AppSkillSource[], SkillDefinitionInvalid>;

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

@@ -0,0 +1,43 @@
+/** Remote skill readers return complete portable bundles, never installed host files. */
+import { Effect } from "effect";
+import { SkillLoadFailed, type GitHubSkillsOptions, type WellKnownSkillsOptions, type SkillTransport } from "../contracts/skills.js";
+/** Give every failure without a message one that names the service. */
+export declare const withService: (service: string | undefined) => <A, R>(effect: Effect.Effect<A, SkillLoadFailed, R>) => Effect.Effect<A, SkillLoadFailed, R>;
+/** One loader invocation owns its byte budget and all of its network requests. */
+export declare const reader: (transport: SkillTransport) => Effect.Effect<{
+    fetchBytes: (url: string, post?: {
+        readonly body: Uint8Array;
+        readonly headers: Record<string, string>;
+    }) => Effect.Effect<Uint8Array<ArrayBuffer>, SkillLoadFailed, never>;
+    read: (url: string) => Effect.Effect<string, SkillLoadFailed, never>;
+    json: (url: string) => Effect.Effect<unknown, SkillLoadFailed, never>;
+}, never, never>;
+export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<readonly {
+    readonly name: string;
+    readonly description: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly license?: string;
+    readonly compatibility?: string;
+    readonly metadata?: {
+        readonly [x: string]: string;
+    };
+    readonly "allowed-tools"?: string;
+}[], SkillLoadFailed, never>;
+/** Fetch all indexed files and reject a publication whose index changes during the read. */
+export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) => Effect.Effect<readonly {
+    readonly name: string;
+    readonly description: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly license?: string;
+    readonly compatibility?: string;
+    readonly metadata?: {
+        readonly [x: string]: string;
+    };
+    readonly "allowed-tools"?: string;
+}[], SkillLoadFailed, never>;

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

@@ -1,10 +1,12 @@
-import { type DatabaseSession } from "../../../app-data/src/index.js";
+import { type DatabaseSession, type reservedFieldNames } from "../../../app-data/src/index.js";
+type ReservedFieldName = (typeof reservedFieldNames)[number];
 import { type AppStorage } from "../contracts/storage.js";
 import type { DatabaseDefinition, Database, Table, Tables } from "../contracts/storage.js";
 import { type Fields } from "./schema.js";
 export type { DatabaseDefinition, Database, DatabaseReader, Table, Tables, RowOf, } from "../contracts/storage.js";
-/** Declare scalar columns using the same schemas as operation inputs. */
-export declare const table: <const F extends Fields>(fields: F) => Table<F>;
+/** Declare scalar columns using the same schemas as operation inputs. The host adds `id`,
+ * `createdAt` and `updatedAt` to every row, so tables cannot declare those names. */
+export declare const table: <const F extends Fields & { readonly [K in ReservedFieldName]?: never; }>(fields: F) => Table<F>;
 /** Build a fresh Promise database facade for one authorized invocation. */
 export declare const authorDatabase: <T extends Tables>(tables: T, session: DatabaseSession, signal: AbortSignal, writable: boolean) => Database<T>;
 /** Declare storage independently of handlers; the host binds each invocation's database. */

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

@@ -0,0 +1,28 @@
+/** Swagger is most of the OpenAPI module's code. Discovery from a cached catalog never needs it,
+ * so a cold app Worker evaluates it only when it resolves a document or builds a request.
+ */
+import "../contracts/swagger-client.ts";
+export type SwaggerClient = typeof import("swagger-client").default;
+export declare const loadSwaggerClient: () => Promise<{
+    buildRequest(options: {
+        spec: unknown;
+        operationId?: string;
+        pathName?: string;
+        method?: string;
+        parameters?: Readonly<Record<string, unknown>>;
+        requestBody?: unknown;
+        requestContentType?: string;
+        securities?: {
+            authorized: Readonly<Record<string, unknown>>;
+        };
+    }): unknown;
+    resolve(options: {
+        spec: unknown;
+        skipNormalization: boolean;
+        useCircularStructures: boolean;
+        requestInterceptor: () => never;
+    }): Promise<{
+        spec: unknown;
+        errors: readonly unknown[];
+    }>;
+}>;