apps 0.0.1-beta.95 → 0.0.1-beta.99

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

@@ -50,7 +50,7 @@ export { DeclaredRequirements, HostRequest } from "./protocols/current.js";
  * classes from `apps/mcp` and `apps/skills`.
  */
 export { McpError, SkillLoadFailed } from "./protocols/current.js";
-export { DeclaredAuthMethod, DeclaredProvider, DeclaredAccountSlot, DeclaredAccountSlots, ResolvedAccount, ResolvedAccounts, ResolvedAccountSlots, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, HostRouterError, HostedRouter, HostedCatalog, HostedCatalogSummary, SkillSources, SkillCatalogResponse, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, HostKindMismatch, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/current.js";
+export { DeclaredAuthMethod, DeclaredProvider, DeclaredAccountSlot, DeclaredAccountSlots, ResolvedAccount, ResolvedAccounts, ResolvedAccountSlots, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, HostRouterError, HostedRouter, HostedCatalog, HostedCatalogSummary, HostedSharedCatalog, HostedSharedTool, SharedSchemaKey, SkillSources, SkillCatalogResponse, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, HostKindMismatch, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/current.js";
 /** Raw host inputs; the host boundary parses and redacts these immediately. */
 export type ResolvedAccountsInput = typeof ResolvedAccounts.Encoded;
 /**
@@ -1479,10 +1479,16 @@ export interface SkillCatalog {
 }
 export declare const skillCatalog: (response: typeof SkillCatalogResponse.Type) => SkillCatalog;
 /**
- * Inspection commands. Send detail or tools only to builds that declare toolIndex,
- * and scheduled only to builds that declare scheduledTools.
+ * Inspection commands. Send detail or tools only to builds that declare toolIndex, scheduled
+ * only to builds that declare scheduledTools, and definitions only to builds that declare
+ * sharedDefinitions: they answer it with a `HostedSharedCatalog`.
  */
-export declare const inspectCommand: (tools?: readonly string[], scheduled?: true) => {
+export declare const inspectCommand: (options: {
+    readonly tools?: readonly string[] | undefined;
+    readonly scheduled?: true | undefined;
+    readonly definitions?: "shared" | undefined;
+}) => {
+    definitions?: "shared";
     scheduled?: true;
     tools?: string[];
     operation: "inspect";
@@ -1491,6 +1497,7 @@ export declare const indexCommand: {
     readonly operation: "inspect";
     readonly detail: "summary";
 };
+export { restoreSharedCatalog } from "./shared-catalog.js";
 /** Keep only the requested tools from an inspection that may have described every tool. */
 export declare const selectTools: (tools?: readonly string[]) => <A extends {
     readonly tools: readonly {

package/types/apps/src/contracts/protocols/current.d.ts

@@ -839,6 +839,11 @@ export declare const DeclaredRequirements: Schema.Struct<{
         readonly skillSources: Schema.optionalKey<Schema.Literal<true>>;
         /** Accepts scheduled inspection. Earlier builds reject it as an excess field. */
         readonly scheduledTools: Schema.optionalKey<Schema.Literal<true>>;
+        /**
+         * Accepts inspect definitions and answers it with a shared catalog. Earlier builds reject it
+         * as an excess field.
+         */
+        readonly sharedDefinitions: Schema.optionalKey<Schema.Literal<true>>;
     }>>;
     /**
      * The document database an app of protocol 9 or earlier declared. Apps of this protocol declare
@@ -2907,6 +2912,110 @@ export declare const HostedCatalogSummary: Schema.Struct<{
     }>>;
 }>;
 export type HostedCatalogSummary = typeof HostedCatalogSummary.Type;
+/** A tool schema whose `$defs` a shared catalog sends once, beside its tools. */
+export declare const SharedSchemaKey: Schema.Literals<readonly ["inputSchema", "outputSchema"]>;
+export type SharedSchemaKey = typeof SharedSchemaKey.Type;
+/**
+ * A tool of a shared catalog. The `$defs` of each schema `shared` names is the position of its
+ * entries in the catalog's `defs`; the tool's other fields are as `HostedTool`'s.
+ */
+export declare const HostedSharedTool: Schema.Struct<{
+    readonly shared: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["inputSchema", "outputSchema"]>>>;
+    readonly schedules: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.NonEmptyString;
+        readonly scope: Schema.optionalKey<Schema.Literal<"app">>;
+        readonly timing: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"interval">;
+            readonly milliseconds: Schema.Int;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"cron">;
+            readonly calendar: Schema.Struct<{
+                readonly expression: Schema.NonEmptyString;
+                readonly timezone: Schema.NonEmptyString;
+            }>;
+        }>]>;
+        readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>>;
+    readonly name: Schema.NonEmptyString;
+    readonly router: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly tags: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
+    readonly description: Schema.String;
+    readonly inputSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly readOnly: Schema.optionalKey<Schema.Boolean>;
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly annotations: Schema.optionalKey<Schema.Struct<{
+        readonly title: Schema.optionalKey<Schema.String>;
+        readonly readOnlyHint: Schema.optionalKey<Schema.Boolean>;
+        readonly destructiveHint: Schema.optionalKey<Schema.Boolean>;
+        readonly idempotentHint: Schema.optionalKey<Schema.Boolean>;
+        readonly openWorldHint: Schema.optionalKey<Schema.Boolean>;
+    }>>;
+    readonly _meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+export type HostedSharedTool = typeof HostedSharedTool.Type;
+/**
+ * A catalog that sends each `$defs` its tools' schemas hold once, and each definition in them
+ * once. Routers such as the OpenAPI importer give every tool the definitions its schemas reach,
+ * which for a densely connected document is most of the document again for each tool, under the
+ * same few hundred `$defs`. Putting each tool's `$defs` back gives the `HostedCatalog` the bundle
+ * evaluated. Only builds that declare the sharedDefinitions capability send it, and only when
+ * the inspection asks.
+ */
+export declare const HostedSharedCatalog: Schema.Struct<{
+    readonly tools: Schema.$Array<Schema.Struct<{
+        readonly shared: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["inputSchema", "outputSchema"]>>>;
+        readonly schedules: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly name: Schema.NonEmptyString;
+            readonly scope: Schema.optionalKey<Schema.Literal<"app">>;
+            readonly timing: Schema.Union<readonly [Schema.Struct<{
+                readonly kind: Schema.Literal<"interval">;
+                readonly milliseconds: Schema.Int;
+            }>, Schema.Struct<{
+                readonly kind: Schema.Literal<"cron">;
+                readonly calendar: Schema.Struct<{
+                    readonly expression: Schema.NonEmptyString;
+                    readonly timezone: Schema.NonEmptyString;
+                }>;
+            }>]>;
+            readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>>>;
+        readonly name: Schema.NonEmptyString;
+        readonly router: Schema.optionalKey<Schema.NonEmptyString>;
+        readonly tags: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
+        readonly description: Schema.String;
+        readonly inputSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly readOnly: Schema.optionalKey<Schema.Boolean>;
+        readonly title: Schema.optionalKey<Schema.String>;
+        readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly annotations: Schema.optionalKey<Schema.Struct<{
+            readonly title: Schema.optionalKey<Schema.String>;
+            readonly readOnlyHint: Schema.optionalKey<Schema.Boolean>;
+            readonly destructiveHint: Schema.optionalKey<Schema.Boolean>;
+            readonly idempotentHint: Schema.optionalKey<Schema.Boolean>;
+            readonly openWorldHint: Schema.optionalKey<Schema.Boolean>;
+        }>>;
+        readonly _meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>>;
+    readonly routers: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.String;
+        readonly title: Schema.optionalKey<Schema.String>;
+        readonly description: Schema.optionalKey<Schema.String>;
+        readonly icons: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly src: Schema.NonEmptyString;
+            readonly mimeType: Schema.optionalKey<Schema.String>;
+            readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+        }>>>;
+        readonly tags: Schema.optionalKey<Schema.$Record<Schema.NonEmptyString, Schema.String>>;
+        readonly skill: Schema.optionalKey<Schema.NonEmptyString>;
+        readonly error: Schema.optionalKey<Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostDeclarationInvalid, typeof HostEvaluationFailed]>>;
+    }>>;
+    readonly definitions: Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    /** Each distinct `$defs`, its entries naming positions in `definitions`. */
+    readonly defs: Schema.$Array<Schema.$Record<Schema.String, Schema.Int>>;
+}>;
+export type HostedSharedCatalog = typeof HostedSharedCatalog.Type;
 /**
  * A skill catalog and whether any of it came from `dynamicSkills`. Without a live loader the
  * catalog is determined by the build and its evaluation inputs; with one it reflects a publisher.
@@ -3055,6 +3164,11 @@ export declare const HostRequest: Schema.Union<readonly [Schema.Union<readonly [
      * Only builds that declare the scheduledTools capability accept this.
      */
     readonly scheduled: Schema.optionalKey<Schema.Literal<true>>;
+    /**
+     * Answer with a HostedSharedCatalog, each shared `$defs` entry sent once. Only builds that
+     * declare the sharedDefinitions capability accept this.
+     */
+    readonly definitions: Schema.optionalKey<Schema.Literal<"shared">>;
 }>, Schema.Struct<{
     readonly operation: Schema.Literal<"skills">;
     /** Answer with SkillSources. Only builds that declare the skillSources capability accept this. */
@@ -3261,6 +3375,11 @@ export declare const HostInvocation: Schema.Struct<{
          * Only builds that declare the scheduledTools capability accept this.
          */
         readonly scheduled: Schema.optionalKey<Schema.Literal<true>>;
+        /**
+         * Answer with a HostedSharedCatalog, each shared `$defs` entry sent once. Only builds that
+         * declare the sharedDefinitions capability accept this.
+         */
+        readonly definitions: Schema.optionalKey<Schema.Literal<"shared">>;
     }>, Schema.Struct<{
         readonly operation: Schema.Literal<"skills">;
         /** Answer with SkillSources. Only builds that declare the skillSources capability accept this. */
@@ -4113,6 +4232,7 @@ export declare const messageDirections: {
     readonly requirements: "bundle";
     readonly catalog: "bundle";
     readonly catalogSummary: "bundle";
+    readonly sharedCatalog: "bundle";
     readonly tools: "bundle";
     readonly toolSummaries: "bundle";
     readonly skills: "bundle";
@@ -4204,6 +4324,11 @@ export declare const current: {
                  * Only builds that declare the scheduledTools capability accept this.
                  */
                 readonly scheduled: Schema.optionalKey<Schema.Literal<true>>;
+                /**
+                 * Answer with a HostedSharedCatalog, each shared `$defs` entry sent once. Only builds that
+                 * declare the sharedDefinitions capability accept this.
+                 */
+                readonly definitions: Schema.optionalKey<Schema.Literal<"shared">>;
             }>, Schema.Struct<{
                 readonly operation: Schema.Literal<"skills">;
                 /** Answer with SkillSources. Only builds that declare the skillSources capability accept this. */
@@ -5112,6 +5237,11 @@ export declare const current: {
              * Only builds that declare the scheduledTools capability accept this.
              */
             readonly scheduled: Schema.optionalKey<Schema.Literal<true>>;
+            /**
+             * Answer with a HostedSharedCatalog, each shared `$defs` entry sent once. Only builds that
+             * declare the sharedDefinitions capability accept this.
+             */
+            readonly definitions: Schema.optionalKey<Schema.Literal<"shared">>;
         }>, Schema.Struct<{
             readonly operation: Schema.Literal<"skills">;
             /** Answer with SkillSources. Only builds that declare the skillSources capability accept this. */
@@ -5166,6 +5296,11 @@ export declare const current: {
                 readonly skillSources: Schema.optionalKey<Schema.Literal<true>>;
                 /** Accepts scheduled inspection. Earlier builds reject it as an excess field. */
                 readonly scheduledTools: Schema.optionalKey<Schema.Literal<true>>;
+                /**
+                 * Accepts inspect definitions and answers it with a shared catalog. Earlier builds reject it
+                 * as an excess field.
+                 */
+                readonly sharedDefinitions: Schema.optionalKey<Schema.Literal<true>>;
             }>>;
             /**
              * The document database an app of protocol 9 or earlier declared. Apps of this protocol declare
@@ -5696,6 +5831,59 @@ export declare const current: {
                 readonly error: Schema.optionalKey<Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostDeclarationInvalid, typeof HostEvaluationFailed]>>;
             }>>;
         }>;
+        readonly sharedCatalog: Schema.Struct<{
+            readonly tools: Schema.$Array<Schema.Struct<{
+                readonly shared: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["inputSchema", "outputSchema"]>>>;
+                readonly schedules: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                    readonly name: Schema.NonEmptyString;
+                    readonly scope: Schema.optionalKey<Schema.Literal<"app">>;
+                    readonly timing: Schema.Union<readonly [Schema.Struct<{
+                        readonly kind: Schema.Literal<"interval">;
+                        readonly milliseconds: Schema.Int;
+                    }>, Schema.Struct<{
+                        readonly kind: Schema.Literal<"cron">;
+                        readonly calendar: Schema.Struct<{
+                            readonly expression: Schema.NonEmptyString;
+                            readonly timezone: Schema.NonEmptyString;
+                        }>;
+                    }>]>;
+                    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+                }>>>;
+                readonly name: Schema.NonEmptyString;
+                readonly router: Schema.optionalKey<Schema.NonEmptyString>;
+                readonly tags: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
+                readonly description: Schema.String;
+                readonly inputSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+                readonly readOnly: Schema.optionalKey<Schema.Boolean>;
+                readonly title: Schema.optionalKey<Schema.String>;
+                readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                readonly annotations: Schema.optionalKey<Schema.Struct<{
+                    readonly title: Schema.optionalKey<Schema.String>;
+                    readonly readOnlyHint: Schema.optionalKey<Schema.Boolean>;
+                    readonly destructiveHint: Schema.optionalKey<Schema.Boolean>;
+                    readonly idempotentHint: Schema.optionalKey<Schema.Boolean>;
+                    readonly openWorldHint: Schema.optionalKey<Schema.Boolean>;
+                }>>;
+                readonly _meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>>;
+            readonly routers: Schema.$Array<Schema.Struct<{
+                readonly path: Schema.String;
+                readonly title: Schema.optionalKey<Schema.String>;
+                readonly description: Schema.optionalKey<Schema.String>;
+                readonly icons: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                    readonly src: Schema.NonEmptyString;
+                    readonly mimeType: Schema.optionalKey<Schema.String>;
+                    readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                    readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+                }>>>;
+                readonly tags: Schema.optionalKey<Schema.$Record<Schema.NonEmptyString, Schema.String>>;
+                readonly skill: Schema.optionalKey<Schema.NonEmptyString>;
+                readonly error: Schema.optionalKey<Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostDeclarationInvalid, typeof HostEvaluationFailed]>>;
+            }>>;
+            readonly definitions: Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            /** Each distinct `$defs`, its entries naming positions in `definitions`. */
+            readonly defs: Schema.$Array<Schema.$Record<Schema.String, Schema.Int>>;
+        }>;
         readonly skills: Schema.Union<readonly [Schema.Struct<{
             readonly skills: Schema.$Array<Schema.Struct<{
                 readonly files: Schema.$Array<Schema.Struct<{

package/types/apps/src/contracts/shared-catalog.d.ts

@@ -0,0 +1,11 @@
+import type { HostedCatalog, HostedRouter, HostedSharedCatalog, HostedTool } from "./protocols/current.js";
+/** A catalog with each definition and each distinct `$defs` its tools' schemas hold sent once. */
+export declare const shareCatalog: (catalog: {
+    readonly tools: ReadonlyArray<HostedTool>;
+    readonly routers: ReadonlyArray<HostedRouter>;
+}) => HostedSharedCatalog;
+/**
+ * The catalog a shared catalog was made from; undefined when it names a definition or `$defs`
+ * it does not send.
+ */
+export declare const restoreSharedCatalog: (catalog: HostedSharedCatalog) => HostedCatalog | undefined;

package/types/utils/src/schema-definitions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Helpers for the `$defs` of JSON Schema documents, shared by the encodings that send or keep each
+ * definition once: an app's shared catalog and a kept tool listing's text.
+ */
+import type { Schema } from "effect";
+/** Add an own entry. Assignment would set the prototype for an entry named `__proto__`. */
+export declare const putEntry: <A>(target: Record<string, A>, name: string, value: A) => void;
+type JsonEntries = {
+    readonly [key: string]: Schema.Json;
+};
+/** A JSON Schema document's `$defs`, when it is an object of entries. */
+export declare const schemaDefinitions: (schema: JsonEntries | undefined) => JsonEntries | undefined;
+export {};