Add executor generate: typed TypeScript client for the tool catalog

Running executor generate against an instance writes one self-contained
TypeScript file: a dependency-free Proxy-based runtime client plus full
input/output types for every visible tool, so
client.github.org.main.issues.create({ title }) is typed end to end and
executes through the server's /api/executions endpoint (auth, policies,
approvals included).

New pieces:
- tools.export SDK surface + GET /tools/export: the bulk schema-bearing
  catalog read (schemas + trimmed shared $defs, grouped per connection,
  policy-filtered), one request regardless of catalog size.
- compileToolChunkTypeScript: compiles many tools per compiler pass. Per-tool
  passes pay fixed overhead thousands of times and one whole-catalog pass is
  super-linear (30s+ at 10k tools); 200-tool chunks generate a 10k-tool
  catalog in ~400ms.
- generateToolProxySource: assembles the generated file (type-only namespaces
  per connection, ExecutorTools path tree, embedded runtime).
- executor generate CLI command with --output/--integration/--connection/
  --include-static, reusing the server-target and auth machinery.

Tested down to the wire: generated source is typechecked with the real
compiler (valid calls accept, invalid reject), the transpiled runtime is
imported and run against a fake fetch (completed/paused/injection paths),
and a scale test ingests a 10,000-operation OpenAPI spec through addSpec and
proves export + generate + strict typecheck hold up with regression
tripwires on time.

Author: RhysSullivan

.changeset/typed-api-proxy-generate.md

@@ -0,0 +1,16 @@
+---
+"@executor-js/sdk": minor
+"executor": minor
+---
+
+Add `executor generate`: emit a typed TypeScript client for an instance's tool catalog.
+
+Running `executor generate` against a server writes a single self-contained
+file (default `executor.gen.ts`) with a dependency-free runtime client and
+full input/output types for every visible tool, so
+`client.github.org.main.issues.create({ title })` is typed end to end and
+calls go through the server's execution endpoint (auth, policies, and
+approvals included). New `GET /tools/export` endpoint and
+`executor.tools.export()` SDK surface return the whole schema-bearing catalog
+in one read; generation compiles schemas in chunks and stays fast at
+10,000-tool scale.

apps/cli/src/main.ts

@@ -69,6 +69,8 @@ import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
 
 import { ExecutorApi, checkForUpdate } from "@executor-js/api";
 import {
+  ConnectionName,
+  IntegrationSlug,
   getExecutorServerAuthorizationHeader,
   normalizeExecutorServerConnection,
   normalizeExecutorServerOrigin,
@@ -77,6 +79,7 @@ import {
   type ExecutorServerConnection,
   type ExecutorServerConnectionInput,
 } from "@executor-js/sdk/shared";
+import { generateToolProxySource } from "@executor-js/sdk/core";
 import {
   decodeAccessTokenClaims,
   discoverCliLogin,
@@ -2710,6 +2713,105 @@ const mcpCommand = Command.make(
     }),
 ).pipe(Command.withDescription("Start an MCP server over stdio"));
 
+// ---------------------------------------------------------------------------
+// Generate — emit a typed TypeScript client for the instance's tool catalog
+// ---------------------------------------------------------------------------
+
+const generateCommand = Command.make(
+  "generate",
+  {
+    output: Options.string("output").pipe(
+      Options.withAlias("o"),
+      Options.withDefault("executor.gen.ts"),
+      Options.withDescription("Path of the generated TypeScript file."),
+    ),
+    integration: Options.string("integration").pipe(
+      Options.optional,
+      Options.withDescription("Only generate tools from this integration slug."),
+    ),
+    connection: Options.string("connection").pipe(
+      Options.optional,
+      Options.withDescription("Only generate tools from this connection name."),
+    ),
+    includeStatic: Options.boolean("include-static").pipe(
+      Options.withDefault(false),
+      Options.withDescription(
+        "Include Executor's built-in static tools (executor.*, search, describe.*).",
+      ),
+    ),
+    baseUrl: serverBaseUrl,
+    server: serverProfile,
+    scope,
+  },
+  ({ output, integration, connection, includeStatic, baseUrl, server, scope }) =>
+    Effect.gen(function* () {
+      applyScope(scope);
+      const target = serverTargetFromOptions({ baseUrl, server });
+      const serverConnection = yield* resolveExecutorServerConnection(target);
+      const client = yield* makeApiClient(serverConnection);
+
+      const catalog = yield* client.tools
+        .export({
+          query: {
+            ...(Option.isSome(integration)
+              ? { integration: IntegrationSlug.make(integration.value) }
+              : {}),
+            ...(Option.isSome(connection)
+              ? { connection: ConnectionName.make(connection.value) }
+              : {}),
+          },
+        })
+        .pipe(Effect.mapError(toError));
+
+      const filtered = includeStatic
+        ? catalog
+        : {
+            connections: catalog.connections
+              .map((entry) => ({
+                ...entry,
+                tools: entry.tools.filter((tool) => tool.static !== true),
+              }))
+              .filter((entry) => entry.tools.length > 0),
+          };
+
+      const generated = yield* Effect.try({
+        try: () => generateToolProxySource(filtered),
+        catch: (cause) =>
+          cause instanceof Error
+            ? cause
+            : new Error(`Failed to generate TypeScript source: ${String(cause)}`),
+      });
+
+      if (generated.toolCount === 0) {
+        return yield* Effect.fail(
+          new Error(
+            [
+              "No tools matched, nothing to generate.",
+              `Server: ${serverConnection.origin}`,
+              `Check filters, or add an integration first: ${cliPrefix} web`,
+            ].join("\n"),
+          ),
+        );
+      }
+
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* PlatformPath.Path;
+      const outputPath = path.isAbsolute(output) ? output : path.join(process.cwd(), output);
+      yield* fs.makeDirectory(path.dirname(outputPath), { recursive: true });
+      yield* fs.writeFileString(outputPath, generated.source);
+
+      console.log(
+        `Generated ${outputPath} (${generated.toolCount} tools, ${generated.connectionCount} connections).`,
+      );
+      console.log("");
+      console.log("Use it:");
+      console.log(`  import { createExecutorClient } from "./${path.basename(output, ".ts")}";`);
+      console.log(`  const executor = createExecutorClient();`);
+    }).pipe(Effect.mapError(toError)),
+).pipe(
+  Command.withDescription("Generate a typed TypeScript client for this instance's tool catalog"),
+);
+
 // ---------------------------------------------------------------------------
 // Service — register the daemon with the OS so it survives app-quit + restart
 // ---------------------------------------------------------------------------
@@ -3112,6 +3214,7 @@ const root = Command.make("executor").pipe(
     daemonCommand,
     serviceCommand,
     mcpCommand,
+    generateCommand,
     openCommand,
     docsCommand,
   ] as const),

apps/docs/local/cli.mdx

@@ -109,3 +109,28 @@ resume it:
 ```bash
 executor resume --execution-id exec_123
 ```
+
+## Generate a typed client
+
+`executor generate` writes a single self-contained TypeScript file with full
+input/output types for every tool in your catalog, plus a dependency-free
+runtime client. Drop it into any TypeScript project and every call is typed
+end to end, while still executing through Executor (auth, policies, and
+approvals included):
+
+```bash
+executor generate                      # writes executor.gen.ts
+executor generate -o src/executor.ts   # custom output path
+executor generate --integration github # only one integration
+```
+
+```ts
+import { createExecutorClient } from "./executor.gen";
+
+const executor = createExecutorClient(); // EXECUTOR_API_KEY / EXECUTOR_AUTH_TOKEN
+const created = await executor.github.org.main.issues.create({ title: "Hi" });
+if (created.ok) console.log(created.data.number);
+```
+
+Calls that pause for approval throw `ExecutorPausedError` with the approval
+URL. Re-run `executor generate` whenever your catalog changes.

packages/core/api/src/handlers/tools.ts

@@ -49,5 +49,20 @@ export const ToolsHandlers = HttpApiBuilder.group(ExecutorApi, "tools", (handler
           return schema;
         }),
       ),
+    )
+    .handle("export", ({ query }) =>
+      capture(
+        Effect.gen(function* () {
+          const executor = yield* ExecutorService;
+          return yield* executor.tools.export({
+            integration: query.integration,
+            owner: query.owner,
+            connection: query.connection,
+            query: query.query,
+            includeAnnotations: query.includeAnnotations === "true",
+            includeBlocked: query.includeBlocked === "true",
+          });
+        }),
+      ),
     ),
 );

packages/core/api/src/tools/api.ts

@@ -16,6 +16,7 @@ import {
   InternalError,
   Owner,
   ToolAddress,
+  ToolCatalogExport,
   ToolNotFoundError,
   ToolSchemaView,
 } from "@executor-js/sdk/shared";
@@ -82,4 +83,15 @@ export const ToolsApi = HttpApiGroup.make("tools")
       success: ToolSchemaView,
       error: [InternalError, ToolNotFound],
     }),
+  )
+  .add(
+    // Bulk schema-bearing read for codegen (`executor generate`): every
+    // visible tool's input/output JSON schema grouped per connection with the
+    // connection's shared `$defs`. One request regardless of catalog size —
+    // per-tool `schema` round trips do not scale to 10k-tool catalogs.
+    HttpApiEndpoint.get("export", "/tools/export", {
+      query: ListToolsQuery,
+      success: ToolCatalogExport,
+      error: InternalError,
+    }),
   );

packages/core/execution/src/promise.ts

@@ -109,6 +109,8 @@ const wrapPromiseExecutor = (pe: PromiseExecutor): EffectExecutor => {
         fromPromise(() => pe.tools.list(filter)),
       schema: (address: Parameters<PromiseExecutor["tools"]["schema"]>[0]) =>
         fromPromise(() => pe.tools.schema(address)),
+      export: (filter?: Parameters<PromiseExecutor["tools"]["export"]>[0]) =>
+        fromPromise(() => pe.tools.export(filter)),
     },
     providers: {
       list: () => fromPromise(() => pe.providers.list()),

packages/core/sdk/src/executor.ts

@@ -136,7 +136,13 @@ import {
   ORG_SUBJECT,
   type ExecutorOwnerPolicyContext,
 } from "./owner-policy";
-import { ToolSchemaView, type IntegrationDetectionResult } from "./types";
+import {
+  ToolCatalogExport,
+  ToolSchemaView,
+  type IntegrationDetectionResult,
+  type ToolCatalogConnectionExport,
+  type ToolCatalogToolExport,
+} from "./types";
 import { type Tool, type ToolAnnotations, type ToolDef, type ToolListFilter } from "./tool";
 import { buildToolTypeScriptPreview } from "./schema-types";
 import { collectReferencedDefinitions } from "./schema-refs";
@@ -304,6 +310,9 @@ export type Executor<TPlugins extends readonly AnyPlugin[] = readonly []> = {
   readonly tools: {
     readonly list: (filter?: ToolListFilter) => Effect.Effect<readonly Tool[], StorageFailure>;
     readonly schema: (address: ToolAddress) => Effect.Effect<ToolSchemaView | null, StorageFailure>;
+    /** Bulk schema-bearing read for codegen: every visible tool's input/output
+     *  JSON schema, grouped per connection with trimmed shared `$defs`. */
+    readonly export: (filter?: ToolListFilter) => Effect.Effect<ToolCatalogExport, StorageFailure>;
   };
 
   readonly providers: {
@@ -2752,6 +2761,126 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
         });
       });
 
+    // The bulk schema-bearing read behind `executor generate`. One pass over
+    // full tool rows (schemas included, unlike the projected `toolsList`),
+    // policy-filtered like `toolsList`, grouped per connection with that
+    // connection's `$defs` trimmed to the referenced subset. Kept as a single
+    // surface instead of N `toolSchema` calls: a 10k-tool catalog must not pay
+    // 10k round trips or 10k per-tool definition queries.
+    const toolsExport = (
+      filter?: ToolListFilter,
+    ): Effect.Effect<ToolCatalogExport, StorageFailure> =>
+      Effect.gen(function* () {
+        yield* syncStaleConnectionTools;
+        const rows = yield* core.findMany("tool", {
+          where: (b: AnyCb) =>
+            b.and(
+              filter?.integration === undefined
+                ? true
+                : b("integration", "=", String(filter.integration)),
+              filter?.owner === undefined ? true : b("owner", "=", filter.owner),
+              filter?.connection === undefined
+                ? true
+                : b("connection", "=", String(filter.connection)),
+            ),
+        });
+        const includeBlocked = filter?.includeBlocked ?? false;
+        const policyRules = yield* listActivePolicyRuleSet();
+
+        type ConnectionGroup = {
+          readonly owner: Owner;
+          readonly integration: IntegrationSlug;
+          readonly connection: ConnectionName;
+          readonly tools: ToolCatalogToolExport[];
+        };
+        const groups = new Map<string, ConnectionGroup>();
+        const groupFor = (tool: Tool): ConnectionGroup => {
+          const key = `${tool.owner}${tool.integration}${tool.connection}`;
+          let group = groups.get(key);
+          if (!group) {
+            group = {
+              owner: tool.owner,
+              integration: tool.integration,
+              connection: tool.connection,
+              tools: [],
+            };
+            groups.set(key, group);
+          }
+          return group;
+        };
+
+        const visible = (tool: Tool): Effect.Effect<boolean, StorageFailure> =>
+          Effect.gen(function* () {
+            if (!matchesToolFilter(tool, filter)) return false;
+            if (includeBlocked) return true;
+            const effective = yield* resolvePolicyFromRuleSet(
+              normalizedPolicyId(tool),
+              policyRules,
+              tool.annotations?.requiresApproval,
+            );
+            return effective.action !== "block";
+          });
+
+        for (const row of rows) {
+          const tool = rowToTool(row);
+          if (!(yield* visible(tool))) continue;
+          groupFor(tool).tools.push({
+            address: tool.address,
+            name: String(tool.name),
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+          });
+        }
+        for (const entry of staticTools.values()) {
+          const tool = staticToolToTool(entry);
+          if (!(yield* visible(tool))) continue;
+          groupFor(tool).tools.push({
+            address: tool.address,
+            name: String(tool.name),
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            static: true,
+          });
+        }
+
+        const connectionsOut: ToolCatalogConnectionExport[] = [];
+        for (const group of groups.values()) {
+          // Static pseudo-connections have no definition rows; skip the query.
+          const isStatic = group.tools.every((tool) => tool.static === true);
+          let definitions: Record<string, unknown> | undefined;
+          if (!isStatic) {
+            const definitionRows = yield* core.findMany("definition", {
+              where: (b: AnyCb) =>
+                b.and(
+                  byOwner(group.owner)(b),
+                  b("integration", "=", String(group.integration)),
+                  b("connection", "=", String(group.connection)),
+                ),
+            });
+            const defs = new Map<string, unknown>();
+            for (const def of definitionRows) defs.set(def.name, decodeJsonColumn(def.schema));
+            const referenced = collectReferencedDefinitions(
+              group.tools.flatMap((tool) => [tool.inputSchema, tool.outputSchema]),
+              defs,
+            );
+            if (Object.keys(referenced).length > 0) {
+              definitions = referenced;
+            }
+          }
+          connectionsOut.push({
+            owner: group.owner,
+            integration: group.integration,
+            connection: group.connection,
+            tools: group.tools,
+            ...(definitions !== undefined ? { definitions } : {}),
+          });
+        }
+
+        return ToolCatalogExport.make({ connections: connectionsOut });
+      });
+
     // ------------------------------------------------------------------
     // Providers
     // ------------------------------------------------------------------
@@ -3465,6 +3594,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
       tools: {
         list: toolsList,
         schema: toolSchema,
+        export: toolsExport,
       },
       providers: {
         list: providersList,