feat: add action catalog endpoint and improve OpenAPI spec handling

Author: frontegg-david

docs/enclave/api-reference/enclavejs-broker.mdx

@@ -193,6 +193,93 @@ Submit tool execution result.
 }
 ```
 
+### GET /code/actions
+
+Returns the current action catalog derived from connected OpenAPI sources.
+
+**Response:**
+```ts
+interface CatalogResponse {
+  /** Available actions from all connected OpenAPI sources */
+  actions: CatalogAction[];
+  /** Connected OpenAPI service descriptors */
+  services: CatalogService[];
+  /** Catalog version — changes when actions are added or removed */
+  version: string;
+}
+
+interface CatalogAction {
+  /** Tool name (e.g., "user-service_listUsers") */
+  name: string;
+  /** Human-readable description from the OpenAPI spec */
+  description?: string;
+  /** JSON Schema for the tool's input parameters */
+  inputSchema?: Record<string, unknown>;
+  /** Name of the service this action belongs to */
+  service: string;
+  /** Tags from the OpenAPI operation */
+  tags?: string[];
+  /** Whether the operation is deprecated */
+  deprecated?: boolean;
+}
+
+interface CatalogService {
+  /** Service name (from OpenApiSourceConfig.name) */
+  name: string;
+  /** Internal spec URL */
+  specUrl: string;
+  /** ISO 8601 timestamp of the last successful spec poll */
+  lastUpdated: string;
+  /** Number of actions from this service */
+  actionCount: number;
+}
+```
+
+**Version semantics:** The `version` field is a deterministic hash of all source spec hashes. It changes whenever an OpenAPI spec is polled with additions or removals. Consumers can compare version strings to detect catalog changes.
+
+**Example:**
+```bash
+curl http://localhost:3001/code/actions
+```
+
+```json
+{
+  "actions": [
+    {
+      "name": "user-service_listUsers",
+      "description": "List all users",
+      "service": "user-service"
+    },
+    {
+      "name": "user-service_getUser",
+      "description": "Get user by ID",
+      "service": "user-service"
+    }
+  ],
+  "services": [
+    {
+      "name": "user-service",
+      "specUrl": "",
+      "lastUpdated": "2026-03-31T12:00:00.000Z",
+      "actionCount": 2
+    }
+  ],
+  "version": "a1b2c3d4..."
+}
+```
+
+**Wiring:** Use `CatalogHandler` to register this route:
+```ts
+import { CatalogHandler } from '@enclave-vm/broker';
+
+const catalog = new CatalogHandler(toolRegistry, openApiSources);
+for (const route of catalog.getRoutes()) {
+  app[route.method.toLowerCase()](route.path, route.handler);
+}
+```
+
+The types `CatalogAction`, `CatalogService`, `CatalogResponse`, and `CatalogHandler` are all exported from the `@enclave-vm/broker` package.
+
 ### GET /health
 
 Health check endpoint.

libs/broker/src/broker-session.ts

@@ -231,17 +231,22 @@ export class BrokerSession {
         stdoutBytes: this.stdoutBytes,
       };
 
-      // If session was cancelled while running, let the catch path handle it
+      // Session was cancelled/terminated while enclave was running
       if (this.isTerminal()) {
+        const cancelError = {
+          code: this._deadlineExceeded ? 'DEADLINE_EXCEEDED' : 'SESSION_CANCELLED',
+          message: 'Session was cancelled',
+        };
+        this.emitter.emitFinalError(cancelError, eventStats);
         result = {
           success: false,
-          error: { message: 'Session was cancelled', name: 'Error', code: 'SESSION_CANCELLED' },
+          error: { message: cancelError.message, name: 'Error', code: cancelError.code },
           stats,
           finalState: 'cancelled',
         };
       } else if (enclaveResult.success) {
         this._state = 'completed';
-        this.emitter.emitFinalSuccess(enclaveResult.value, eventStats);
+        this.emitter.emitFinalSuccess(enclaveResult.value, eventStats, this.getPartialErrors());
         result = {
           success: true,
           value: enclaveResult.value,
@@ -254,7 +259,7 @@ export class BrokerSession {
           code: enclaveResult.error?.code ?? 'EXECUTION_ERROR',
           message: enclaveResult.error?.message ?? 'Execution failed',
         };
-        this.emitter.emitFinalError(errorInfo, eventStats);
+        this.emitter.emitFinalError(errorInfo, eventStats, this.getPartialErrors());
         result = {
           success: false,
           error: {
@@ -299,7 +304,7 @@ export class BrokerSession {
           : ((err as Error & { code?: string }).code ?? 'EXECUTION_ERROR'),
         message: err.message,
       };
-      this.emitter.emitFinalError(errorInfo, eventStats);
+      this.emitter.emitFinalError(errorInfo, eventStats, this.getPartialErrors());
       result = {
         success: false,
         error: {
@@ -417,14 +422,13 @@ export class BrokerSession {
   }
 
   /**
-   * Create a custom event with proper base fields.
-   * Uses the emitter's current seq (no auto-increment for custom events).
+   * Create a custom event with proper base fields and unique sequence number.
    */
   private makeCustomEvent(type: string, payload: Record<string, unknown>): StreamEvent {
     return {
       protocolVersion: PROTOCOL_VERSION,
       sessionId: this.sessionId,
-      seq: this.seq,
+      seq: this.emitter.nextSeq(),
       type,
       payload,
     } as unknown as StreamEvent;
@@ -467,6 +471,7 @@ export class BrokerSession {
           toolCallCount: this.toolCallCount,
           stdoutBytes: this.stdoutBytes,
         },
+        this.getPartialErrors(),
       );
     }
   }

libs/broker/src/openapi/catalog-handler.ts

@@ -116,8 +116,11 @@ export class CatalogHandler {
       });
     }
 
-    // Version is a hash of all source hashes
-    const versionParts = this.sources.map((s) => s.getStats().specHash).join(':');
+    // Version is a deterministic hash of all source hashes (sorted for stability)
+    const versionParts = this.sources
+      .map((s) => s.getStats().specHash)
+      .sort()
+      .join(':');
     const version = versionParts || 'empty';
 
     return { actions, services, version };

libs/broker/src/openapi/hash-utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Cross-platform SHA-256 hashing utility.
+ *
+ * Uses Web Crypto API (crypto.subtle) which is available in both
+ * Node.js 18+ and modern browsers.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Compute SHA-256 hex digest of a string.
+ */
+export async function sha256Hex(data: string): Promise<string> {
+  const encoded = new TextEncoder().encode(data);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', encoded);
+  const hashArray = new Uint8Array(hashBuffer);
+  return Array.from(hashArray)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}

libs/broker/src/openapi/openapi-spec-poller.ts

@@ -8,7 +8,7 @@
  */
 
 import { EventEmitter } from 'events';
-import { createHash } from 'node:crypto';
+import { sha256Hex } from './hash-utils';
 
 /**
  * Change detection strategy.
@@ -243,7 +243,7 @@ export class OpenApiSpecPoller extends EventEmitter {
 
       if (this._stopped) return;
 
-      const hash = createHash('sha256').update(body).digest('hex');
+      const hash = await sha256Hex(body);
 
       if (this.lastHash && this.lastHash === hash) {
         this.emit('unchanged');

libs/broker/src/openapi/openapi-tool-loader.ts

@@ -8,7 +8,7 @@
  */
 
 import { z } from 'zod';
-import { createHash } from 'node:crypto';
+import { sha256Hex } from './hash-utils';
 import type { ToolDefinition, ToolContext } from '../tool-registry';
 
 /**
@@ -72,10 +72,10 @@ export class OpenApiToolLoader {
   private readonly options: LoaderOptions;
   private readonly auth?: UpstreamAuth;
 
-  private constructor(spec: Record<string, unknown>, options: LoaderOptions = {}, auth?: UpstreamAuth) {
+  private constructor(spec: Record<string, unknown>, hash: string, options: LoaderOptions = {}, auth?: UpstreamAuth) {
     this.options = options;
     this.auth = auth;
-    this.specHash = createHash('sha256').update(JSON.stringify(spec)).digest('hex');
+    this.specHash = hash;
     this.loadFromSpec(spec);
   }
 
@@ -103,7 +103,8 @@ export class OpenApiToolLoader {
       throw new Error(`Failed to fetch OpenAPI spec from ${url}: ${response.status}`);
     }
     const spec = (await response.json()) as Record<string, unknown>;
-    return new OpenApiToolLoader(spec, { ...options, baseUrl: options?.baseUrl ?? new URL(url).origin }, auth);
+    const hash = await sha256Hex(JSON.stringify(spec));
+    return new OpenApiToolLoader(spec, hash, { ...options, baseUrl: options?.baseUrl ?? new URL(url).origin }, auth);
   }
 
   /**
@@ -114,7 +115,8 @@ export class OpenApiToolLoader {
     options?: LoaderOptions,
     auth?: UpstreamAuth,
   ): Promise<OpenApiToolLoader> {
-    return new OpenApiToolLoader(spec, options, auth);
+    const hash = await sha256Hex(JSON.stringify(spec));
+    return new OpenApiToolLoader(spec, hash, options, auth);
   }
 
   /**
@@ -217,10 +219,11 @@ export class OpenApiToolLoader {
   private buildArgsSchema(op: ParsedOperation): z.ZodType {
     const shape: Record<string, z.ZodType> = {};
 
-    // Add parameters
+    // Add parameters with OpenAPI type mapping
     if (op.parameters) {
       for (const param of op.parameters) {
-        shape[param.name] = param.required ? z.string() : z.string().optional();
+        const baseType = this.mapOpenApiType(param.schema);
+        shape[param.name] = param.required ? baseType : baseType.optional();
       }
     }
 
@@ -234,6 +237,34 @@ export class OpenApiToolLoader {
     return Object.keys(shape).length > 0 ? z.object(shape) : z.record(z.string(), z.unknown());
   }
 
+  /**
+   * Map an OpenAPI schema type to the corresponding Zod type.
+   */
+  private mapOpenApiType(schema?: Record<string, unknown>): z.ZodType {
+    if (!schema || !schema['type']) return z.string();
+
+    const type = schema['type'] as string;
+    const enumValues = schema['enum'] as string[] | undefined;
+
+    switch (type) {
+      case 'integer':
+        return z.number().int();
+      case 'number':
+        return z.number();
+      case 'boolean':
+        return z.boolean();
+      case 'array':
+        return z.array(this.mapOpenApiType(schema['items'] as Record<string, unknown> | undefined));
+      case 'string':
+        if (enumValues && enumValues.length > 0) {
+          return z.enum(enumValues as [string, ...string[]]);
+        }
+        return z.string();
+      default:
+        return z.string();
+    }
+  }
+
   /**
    * Create a handler function for an OpenAPI operation.
    */
@@ -267,9 +298,10 @@ export class OpenApiToolLoader {
         url += `?${queryString}`;
       }
 
-      // Build request headers
+      // Build request headers (only set Content-Type for methods with a body)
+      const hasBody = ['post', 'put', 'patch'].includes(op.method) && params['body'] != null;
       const requestHeaders: Record<string, string> = {
-        'Content-Type': 'application/json',
+        ...(hasBody && { 'Content-Type': 'application/json' }),
         ...headers,
       };
 
@@ -304,8 +336,7 @@ export class OpenApiToolLoader {
         signal: context.signal,
       };
 
-      // Add body for methods that support it
-      if (['post', 'put', 'patch'].includes(op.method) && params['body']) {
+      if (hasBody) {
         fetchOptions.body = JSON.stringify(params['body']);
       }
 

libs/client/src/types.ts

@@ -6,7 +6,7 @@
  * @packageDocumentation
  */
 
-import type { SessionId, StreamEvent, SessionLimits } from '@enclave-vm/types';
+import type { SessionId, StreamEvent, SessionLimits, ErrorPayload, ToolProgressPhase } from '@enclave-vm/types';
 
 /**
  * Client configuration
@@ -124,12 +124,12 @@ export interface SessionEventHandlers {
   /**
    * Called when a partial result arrives
    */
-  onPartialResult?: (path: string[], data?: unknown, error?: unknown, hasNext?: boolean) => void;
+  onPartialResult?: (path: string[], data?: unknown, error?: ErrorPayload, hasNext?: boolean) => void;
 
   /**
    * Called when tool progress is reported
    */
-  onToolProgress?: (callId: string, phase: string, elapsedMs: number) => void;
+  onToolProgress?: (callId: string, phase: ToolProgressPhase, elapsedMs: number) => void;
 
   /**
    * Called when deadline is exceeded