openapi: stream compile + serve from content-addressed bindings (no re-parse)

The serve path (resolveOpenApiBackedTools, the 2nd OOM site) re-parsed the
whole spec on every tools/list. For the full Microsoft Graph spec (37MB /
16.5k ops) that rebuilt a ~300MB document tree and OOM'd the 128MB Workers
isolate even after the add-path parser swap.

Add a memory-safe compile + serve path that never re-parses:

- streamOperationBindings (extract.ts): two-pass streaming compile. Pass 1
  plans tool paths from schema-free metadata (planToolPaths, extracted from
  compileToolDefinitions); pass 2 builds invocation bindings in bounded
  chunks, flushing each before the next so a huge spec's bindings are never
  all co-resident with the parsed tree.
- Content-addressed defs blob (store.ts: putDefs/getDefs, keyed by specHash):
  the normalized #/$defs schemas, built once per spec at add time and shared
  across tenants. buildDefsJson serializes them one schema at a time so the
  normalized tree never co-resides with the parsed document.
- Persist a resolved description per operation so the serve path rebuilds each
  tool def from the binding alone.
- resolveOpenApiBackedTools fast path: getDefs(specHash) + listOperations +
  toolDefFromStoredOperation, falling back to a spec re-parse for legacy rows
  or a missing/corrupt blob.
- Route the openapi, microsoft (full-graph), and google add/update paths
  through the streaming persist + putDefs.

Author: RhysSullivan

packages/plugins/google/src/sdk/plugin.ts

@@ -143,6 +143,7 @@ const makeGooglePluginExtension = (
       };
 
       yield* ctx.storage.putSpec(specHash, conversion.specText);
+      yield* ctx.storage.putDefs(specHash, JSON.stringify(compiled.hoistedDefs));
 
       yield* ctx.transaction(
         Effect.gen(function* () {
@@ -183,6 +184,7 @@ const makeGooglePluginExtension = (
 
       const specHash = yield* sha256Hex(conversion.specText);
       yield* ctx.storage.putSpec(specHash, conversion.specText);
+      yield* ctx.storage.putDefs(specHash, JSON.stringify(compiled.hoistedDefs));
 
       const nextConfig: GoogleIntegrationConfig = {
         ...current,
@@ -298,7 +300,8 @@ export const googlePlugin = definePlugin((options?: GooglePluginOptions) => ({
   describeAuthMethods: describeGoogleAuthMethods,
   describeIntegrationDisplay: describeGoogleIntegrationDisplay,
 
-  resolveTools: ({ config, storage }) => resolveOpenApiBackedTools({ config, storage }),
+  resolveTools: ({ integration, config, storage }) =>
+    resolveOpenApiBackedTools({ integration, config, storage }),
 
   invokeTool: ({ ctx, toolRow, credential, args }) => {
     const httpClientLayer = options?.httpClientLayer ?? ctx.httpClientLayer;

packages/plugins/microsoft/src/sdk/plugin.test.ts

@@ -33,6 +33,7 @@ paths:
   /me:
     get:
       operationId: me.GetUser
+      summary: Get the signed-in user profile
       security:
         - azureAdDelegated:
             - User.Read
@@ -341,6 +342,45 @@ describe("Microsoft Graph provider", () => {
         expect(delegated?.kind === "oauth2" ? delegated.scopes : undefined).toEqual([
           ...MICROSOFT_GRAPH_DELEGATED_DEFAULT_SCOPES,
         ]);
+
+        // Full-graph add routes through the streaming `parsedDocument` persist
+        // branch (the path the real 37MB spec takes): it persists each op's
+        // binding plus a `description` and writes the content-addressed defs
+        // blob, never re-parsing on serve. Read the operations back through the
+        // live serve path to prove they landed in storage AND that the serve
+        // fast path rebuilds tools from the persisted bindings (no spec parse).
+        yield* executor.connections.create({
+          owner: "org",
+          name: ConnectionName.make("full"),
+          integration: IntegrationSlug.make("microsoft_graph_full"),
+          template: AuthTemplateSlug.make(MICROSOFT_AUTH_TEMPLATE_SLUG),
+          value: "token-xyz",
+        });
+
+        const tools = yield* executor.tools.list();
+        const toolNames = tools.map((tool) => String(tool.name));
+        expect(toolNames).toContain("me.getUser");
+        expect(toolNames).toContain("me.messagesListMessages");
+        expect(toolNames).toContain("sites.listSites");
+
+        // The serve fast path must rebuild every tool's description from the
+        // persisted operation, not drop it. Each graph tool carries a non-empty
+        // description.
+        for (const tool of tools) {
+          expect(tool.description.length).toBeGreaterThan(0);
+        }
+
+        // `me.getUser`'s spec summary survives the add -> persist -> serve
+        // round-trip. The bare `${METHOD} ${path}` fallback inside the serve
+        // path would be "GET /me", so matching the summary proves the persisted
+        // `description` field is what's served.
+        const getUser = tools.find((tool) => String(tool.name) === "me.getUser");
+        expect(getUser?.description).toBe("Get the signed-in user profile");
+
+        // An op without a spec summary falls back to `${METHOD} ${path}`, also
+        // sourced from the persisted binding on the serve fast path.
+        const listSites = tools.find((tool) => String(tool.name) === "sites.listSites");
+        expect(listSites?.description).toBe("GET /sites");
       }),
     ),
   );

packages/plugins/microsoft/src/sdk/plugin.ts

@@ -15,21 +15,25 @@ import {
   type IntegrationConfig,
   type IntegrationRecord,
   type PluginCtx,
+  type StorageFailure,
 } from "@executor-js/sdk/core";
 import { describeApiKeyAuthMethod } from "@executor-js/sdk/http-auth";
 import {
-  compileOpenApiDocument,
-  compileOpenApiSpec,
+  compileAndPersistOpenApiOperations,
+  compileAndPersistOpenApiSpec,
   decodeOpenApiIntegrationConfig,
   invokeOpenApiBackedTool,
   makeDefaultOpenapiStore,
   normalizeOpenApiAuthInputs,
-  openApiStoredOperationsFromCompiled,
+  OpenApiExtractionError,
+  OpenApiParseError,
   resolveOpenApiBackedAnnotations,
   resolveOpenApiBackedTools,
   type Authentication,
   type AuthenticationInput,
+  type OpenApiPersistResult,
   type OpenapiStore,
+  type ParsedDocument,
 } from "@executor-js/plugin-openapi";
 
 import {
@@ -122,13 +126,31 @@ const makeMicrosoftPluginExtension = (
   ctx: PluginCtx<OpenapiStore>,
   httpClientLayer: Layer.Layer<HttpClient.HttpClient, never, never>,
 ) => {
+  const persistGraphOperations = (
+    graph: { readonly parsedDocument?: ParsedDocument; readonly specText: string },
+    integration: string,
+    specHash: string,
+  ): Effect.Effect<
+    OpenApiPersistResult,
+    OpenApiExtractionError | OpenApiParseError | StorageFailure
+  > =>
+    graph.parsedDocument !== undefined
+      ? compileAndPersistOpenApiOperations({
+          doc: graph.parsedDocument,
+          integration,
+          storage: ctx.storage,
+          specHash,
+        })
+      : compileAndPersistOpenApiSpec({
+          specText: graph.specText,
+          integration,
+          storage: ctx.storage,
+          specHash,
+        });
+
   const addGraph = (config: MicrosoftGraphConfig) =>
     Effect.gen(function* () {
       const graph = yield* buildMicrosoftGraphOpenApiSpec(config, httpClientLayer);
-      const compiled =
-        graph.parsedDocument !== undefined
-          ? yield* compileOpenApiDocument(graph.parsedDocument)
-          : yield* compileOpenApiSpec(graph.specText);
       const slug = IntegrationSlug.make(config.slug?.trim() || DEFAULT_MICROSOFT_SLUG);
 
       const existing = yield* ctx.core.integrations.get(slug);
@@ -156,7 +178,7 @@ const makeMicrosoftPluginExtension = (
 
       yield* ctx.storage.putSpec(specHash, graph.specText);
 
-      yield* ctx.transaction(
+      const persisted = yield* ctx.transaction(
         Effect.gen(function* () {
           yield* ctx.core.integrations.register({
             slug,
@@ -167,14 +189,11 @@ const makeMicrosoftPluginExtension = (
             canRemove: true,
             canRefresh: true,
           });
-          yield* ctx.storage.putOperations(
-            String(slug),
-            openApiStoredOperationsFromCompiled(String(slug), compiled),
-          );
+          return yield* persistGraphOperations(graph, String(slug), specHash);
         }),
       );
 
-      return { slug, toolCount: compiled.definitions.length };
+      return { slug, toolCount: persisted.toolCount };
     });
 
   const updateGraph = (rawSlug: string, input?: MicrosoftUpdateInput) =>
@@ -199,14 +218,8 @@ const makeMicrosoftPluginExtension = (
         },
         httpClientLayer,
       );
-      const compiled =
-        graph.parsedDocument !== undefined
-          ? yield* compileOpenApiDocument(graph.parsedDocument)
-          : yield* compileOpenApiSpec(graph.specText);
-
       const previousOperations = yield* ctx.storage.listOperations(rawSlug);
       const previousNames = new Set(previousOperations.map((op) => op.toolName));
-      const nextNames = new Set(compiled.definitions.map((def) => def.toolPath));
 
       const specHash = yield* sha256Hex(graph.specText);
       yield* ctx.storage.putSpec(specHash, graph.specText);
@@ -229,17 +242,15 @@ const makeMicrosoftPluginExtension = (
         ...(input?.baseUrl ? { baseUrl: input.baseUrl } : {}),
       };
 
-      yield* ctx.transaction(
+      const persisted = yield* ctx.transaction(
         Effect.gen(function* () {
           yield* ctx.core.integrations.update(slug, {
             config: nextConfig satisfies MicrosoftGraphIntegrationConfig as IntegrationConfig,
           });
-          yield* ctx.storage.putOperations(
-            rawSlug,
-            openApiStoredOperationsFromCompiled(rawSlug, compiled),
-          );
+          return yield* persistGraphOperations(graph, rawSlug, specHash);
         }),
       );
+      const nextNames = new Set(persisted.toolNames);
 
       const connections = yield* ctx.connections.list({ integration: slug });
       yield* Effect.forEach(
@@ -257,7 +268,7 @@ const makeMicrosoftPluginExtension = (
 
       return {
         slug,
-        toolCount: compiled.definitions.length,
+        toolCount: persisted.toolCount,
         addedTools: [...nextNames].filter((name) => !previousNames.has(name)).sort(),
         removedTools: [...previousNames].filter((name) => !nextNames.has(name)).sort(),
       };
@@ -340,7 +351,8 @@ export const microsoftPlugin = definePlugin((options?: MicrosoftPluginOptions) =
   describeAuthMethods: describeMicrosoftAuthMethods,
   describeIntegrationDisplay: describeMicrosoftIntegrationDisplay,
 
-  resolveTools: ({ config, storage }) => resolveOpenApiBackedTools({ config, storage }),
+  resolveTools: ({ integration, config, storage }) =>
+    resolveOpenApiBackedTools({ integration, config, storage }),
 
   invokeTool: ({ ctx, toolRow, credential, args }) => {
     const httpClientLayer = options?.httpClientLayer ?? ctx.httpClientLayer;