apps 0.0.1-beta.1 → 0.0.1-beta.2

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

@@ -90,19 +90,28 @@ export interface SkillTransport {
 export interface SkillReaderOptions extends SkillTransport {
     readonly service: string;
 }
-/** A public GitHub repository and an optional immutable commit, tag or branch. */
-export interface GitHubSkillsOptions extends SkillTransport {
+/**
+ * Catalog reuse shared by remote skill loaders, with the same policy as MCP tool catalogs. Pass
+ * `ctx.cache` to keep the loaded catalog; without it every read fetches the source again.
+ */
+export interface SkillCacheOptions {
+    readonly cache?: import("./cache.js").AppCache;
+    /** Reuse the catalog for this duration. Defaults to five minutes. */
+    readonly freshFor?: import("effect").Duration.Input;
+    /** Serve the retained catalog while refreshing. Defaults to one day. */
+    readonly staleFor?: import("effect").Duration.Input;
+}
+/**
+ * A public GitHub repository and an optional immutable commit, tag or branch. With a cache, a
+ * branch or tag is resolved again when the catalog refreshes, and each commit's file list is kept.
+ */
+export interface GitHubSkillsOptions extends SkillTransport, SkillCacheOptions {
     readonly repo: string;
     readonly path?: string;
     readonly ref?: string;
-    /**
-     * Pass `ctx.cache` to keep each commit's skill file list. Content at a commit never changes,
-     * so later reads of the same commit skip the tree fetch. The ref is still resolved each read.
-     */
-    readonly cache?: import("./cache.js").AppCache;
 }
 /** A published directory index, including its listed skill documents and text references. */
-export interface WellKnownSkillsOptions extends SkillTransport {
+export interface WellKnownSkillsOptions extends SkillTransport, SkillCacheOptions {
     readonly url: string;
 }
 /** A folder in the deployed package; omitted path selects skills/. No host filesystem access. */

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

@@ -3,4 +3,6 @@ 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) => AppCache;
+export declare const authorCache: (host: HostCache, accounts: ResolvedAccounts, signal: AbortSignal, 
+/** The invocation's trusted deadline. Waiting on another caller's load never runs past it. */
+deadline?: number) => AppCache;

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

@@ -1,7 +1,6 @@
 /** Compile an OpenAPI document into tool declarations inside the app runtime, never a second execution engine. */
 import { Effect, Schema } from "effect";
 import { JsonObject } from "../contracts/schema.js";
-import "../contracts/swagger-client.ts";
 import { OpenapiCompileError as TemplateError } from "../contracts/openapi-compile.js";
 import type { OpenApiImport } from "../contracts/openapi-document.js";
 import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/openapi-document.js";
@@ -68,6 +67,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly outputSchema?: {
             readonly [x: string]: Schema.Json;
         };
+        readonly operationId?: string;
         readonly streaming?: true;
         readonly errorResponses?: readonly {
             readonly code: string;

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

@@ -1,5 +1,3 @@
-/** OpenAPI reference and dialect rules, shared by every part of the app importer. */
-import "../contracts/swagger-client.ts";
 import { Schema } from "effect";
 import { JsonObject } from "../contracts/schema.js";
 /** Resolve OpenAPI objects once with Swagger; schemas retain their original recursive references.

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

@@ -0,0 +1,18 @@
+/**
+ * Group generated OpenAPI tool names as `<group>.<leaf>`, ported from Executor v1's tool paths.
+ * The group is the first tag, or the first meaningful path segment. The leaf is the operationId
+ * without a repeated group prefix, or a method-and-path name when there is no operationId.
+ */
+export interface OperationNameInput {
+    readonly operationId: string | undefined;
+    /** The first non-empty tag. */
+    readonly tag: string | undefined;
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * Plan one name per input, in input order. Names that collide are refined together: first by
+ * the path's version segment, then by the HTTP method, then by a stable hash. Refinement only
+ * touches the colliding names, so adding an operation never renames an unrelated one.
+ */
+export declare const planOperationNames: (inputs: readonly OperationNameInput[]) => string[];

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

@@ -1,4 +1,3 @@
-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";

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

@@ -2,7 +2,7 @@
 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 { JsonObject, 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. */
@@ -18,6 +18,10 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
     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 {

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

@@ -80,11 +80,6 @@ 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>, ValidationError, never>;

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[];
+    }>;
+}>;

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

@@ -1,6 +1,9 @@
 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 { SkillLoadFailed, SkillDefinitionInvalid, SkillServiceName, type SkillReaderOptions, type FolderSkillsOptions, type AppSkillSource as Skill, type SkillFile, 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.
+ */
 export declare const githubSkills: (options: GitHubSkillsOptions) => Promise<readonly {
     readonly name: string;
     readonly description: string;
@@ -15,7 +18,7 @@ export declare const githubSkills: (options: GitHubSkillsOptions) => Promise<rea
     };
     readonly "allowed-tools"?: string;
 }[]>;
-/** Fetch a published skill index and its text files, with no persistent cache. */
+/** 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;