apps 0.0.1-beta.0 → 0.0.1-beta.1

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

@@ -1,11 +1,18 @@
-/** HTTP serialization for normalized OpenAPI operations. */
+import "../contracts/swagger-client.ts";
+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, type JsonValue } from "../contracts/schema.js";
+import type { DynamicTools } from "../contracts/dynamic-tools.js";
+import { type OperationKinds } from "./protocol-operations.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;
+    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 liveOpenapiOperations: (options: OpenapiSourceOptions) => {
+    readonly queries: {};
+    readonly mutations: {};
+    readonly dynamicTools: DynamicTools;
+};

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

@@ -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,14 @@ export declare const compileJsonSchemaDecoder: (document: JsonObject) => Effect.
         readonly [x: string]: EffectSchema.Json;
     };
 }, ValidationError, never>;
+/**
+ * Build the document only when a value is first decoded or the schema is described, then
+ * compile its validator once. Imported apps can share definitions between many schemas
+ * without making each one self-contained up front.
+ */
+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. */

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

@@ -1,3 +1,6 @@
+export { ProviderError } from "./contracts/provider-error.js";
+export type { AppCache, CacheLoadContext, CacheGetOptions } from "./contracts/cache.js";
+export { CacheError } from "../../app-cache/src/contracts/cache.js";
 /**
  * Public author API. Native contracts live in contracts/; this boundary
  * exposes ordinary declarations, schema helpers and Promise operations.
@@ -14,6 +17,9 @@ export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Sche
 export { type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type OAuth2Config, type Provider, } from "./contracts/provider.js";
 export { defineProvider } from "./implementation/provider.js";
 export { accountOperations } from "./implementation/account-operations.js";
+export { dynamicTools } from "./implementation/dynamic-tools.js";
+export { dynamicSkills } from "./implementation/dynamic-skills.js";
+export type { HostedTool as OperationDescription } from "./contracts/host.js";
 /** A secrets declaration inferred from an author schema. */
 export type SecretsMethod<Shape extends ObjectSchema<Fields>> = NativeSecretsMethod<EffectSchema.Decoder<Infer<Shape>>>;
 /** An OAuth declaration inferred from its author-facing response schema. */
@@ -56,3 +62,4 @@ 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";
 export { interval, cron, type ScheduleDeclaration } from "./implementation/schedules.js";
+export type { AppSkillSource as Skill, SkillFile } from "./contracts/skills.js";

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

@@ -1,10 +1,10 @@
 /** HTTP MCP helpers. Requires the optional @modelcontextprotocol/sdk peer. */
-import { type OperationKinds } from "./implementation/protocol-operations.js";
-import type { McpToolsOptions } from "./contracts/mcp.js";
+import type { OperationKinds } from "./implementation/protocol-operations.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";
 /** Discover operations for the selected account. Kinds override uncertain upstream read-only hints. */
-export declare const mcpOperations: (options: McpToolsOptions, kinds?: OperationKinds) => Promise<{
-    queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
-    mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
+export declare const mcpOperations: (options: McpCatalogOptions, kinds?: OperationKinds) => Promise<{
+    dynamicTools: import("./contracts/dynamic-tools.js").DynamicTools;
 }>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";

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

@@ -1,10 +1,12 @@
 /** OpenAPI helpers over normalized operation metadata; no optional dependency is needed. */
 import { type OperationKinds } from "./implementation/protocol-operations.js";
 import type { OpenapiToolsOptions } from "./contracts/openapi.js";
-export { OpenapiError, type OpenapiToolsOptions, type OpenapiOperation, type CredentialBinding, type RequestParameter, } from "./contracts/openapi.js";
+export { OpenapiError, isOpenapiTextMedia, openapiBinaryResultSchema, OpenapiErrorResponse, type OpenapiToolsOptions, type OpenapiOperation, type CredentialBinding, OpenapiParameter, OpenapiRequestBody, openapiMediaKind, } from "./contracts/openapi.js";
 /** Discover operations for the selected account. Kinds override uncertain upstream read-only hints. */
 export declare const openapiOperations: (options: OpenapiToolsOptions, kinds?: OperationKinds) => Promise<{
     queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
     mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
 }>;
 export type { OperationKinds } from "./implementation/protocol-operations.js";
+export * from "./contracts/openapi-compile.js";
+export { liveOpenapiOperations, type OpenapiSourceOptions, } from "./implementation/openapi-source.js";

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

@@ -0,0 +1,72 @@
+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 WellKnownSkillsOptions, } from "./contracts/skills.js";
+/** Fetch a public GitHub skill collection from one resolved commit. Mutable refs refresh on each call. */
+export declare const githubSkills: (options: GitHubSkillsOptions) => Promise<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;
+}[]>;
+/** Fetch a published skill index and its text files, with no persistent cache. */
+export declare const wellKnownSkills: (options: WellKnownSkillsOptions) => Promise<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;
+}[]>;
+/** 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 files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly license?: string;
+    readonly compatibility?: string;
+    readonly metadata?: {
+        readonly [x: string]: string;
+    };
+    readonly "allowed-tools"?: string;
+}>;
+/** 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 files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly license?: string;
+    readonly compatibility?: string;
+    readonly metadata?: {
+        readonly [x: string]: string;
+    };
+    readonly "allowed-tools"?: string;
+}[]>;
+/**
+ * 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`.
+ */
+export declare const skillReader: (options: SkillReaderOptions) => {
+    /** Fetch one UTF-8 text file. */
+    text: (url: string) => Promise<string>;
+    /** Fetch and parse one JSON document. */
+    json: (url: string) => Promise<unknown>;
+};

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

@@ -1,5 +1,7 @@
 /** Telemetry configuration is parsed at composition roots; headers remain redacted. */
 import { Config, Context, Effect, Schema } from "effect";
+/** Bound each collector request, including its acknowledgement; exporter retries retain the batch. */
+export declare const telemetryRequestTimeout: "5 seconds";
 /** One private exporter target. Endpoints are complete signal URLs. */
 export declare const TelemetryTarget: Schema.Struct<{
     readonly url: Schema.String;