feat(automation): connector discovery endpoint + worked connector_action example (ADR-0022) (#1419)

xuyushun441-sys · os-zhuang · web-flow · commit cd84de3434c7 · 2026-06-01T00:23:22.000+08:00
Tier 1 of the connector roadmap: make the registered-connector set
discoverable so the flow designer can populate the connector_action
node's connector / action / input pickers.

- engine: add getConnectorDescriptors() returning a designer-facing
  view per registered connector (identity + actions' input/output
  JSON Schema); handlers are runtime code, omitted from the metadata.
  New ConnectorDescriptor / ConnectorActionDescriptor types exported.
- runtime: add GET /api/v1/automation/connectors (ADR-0022), mirroring
  GET /actions — ordered before the /:name flow catch-all, supports a
  ?type filter, and reports an empty registry rather than 404 when the
  service lacks the optional method.
- examples/app-showcase: add TaskCompletedSlackFlow, the worked
  connector_action example dispatching to the slack connector's
  chat.postMessage (the 'raw API call' path from ADR-0022).

Tests: engine descriptor unit tests + dispatcher /connectors route
tests (filter, catch-all shadowing, empty-registry fallback). All
service-automation (89) and runtime (329) tests green; showcase
typechecks.

Co-authored-by: Jack Zhuang &lt;277994282+os-zhuang@users.noreply.github.com&gt;
diff --git a/examples/app-showcase/src/flows/index.ts b/examples/app-showcase/src/flows/index.ts
@@ -154,4 +154,63 @@ export const BudgetApprovalFlow = defineFlow({
   ],
 });
 
-export const allFlows = [TaskCompletedFlow, ReassignWizardFlow, BudgetApprovalFlow];
+/**
+ * Task Completed → Post to Slack — the worked `connector_action` example
+ * (ADR-0018 §Addendum, ADR-0022).
+ *
+ * Unlike {@link TaskCompletedFlow}, which hand-waves notification via a `script`
+ * node, this flow takes the "raw API call" path: a baseline `connector_action`
+ * node dispatches to the `slack` connector's `chat.postMessage` action. The
+ * `connector_action` node type is built into every automation engine; the
+ * `slack` connector itself is contributed at runtime by the
+ * `@objectstack/connector-slack` plugin (static bot-token auth). Load that
+ * plugin in your stack and the node resolves; omit it and the step fails with a
+ * clear "connector slack not registered" error rather than silently no-op'ing.
+ *
+ * The connector → action → input pickers the designer shows for this node are
+ * fed by `GET /api/v1/automation/connectors`, which enumerates the live
+ * registry (see `getConnectorDescriptors`).
+ */
+export const TaskCompletedSlackFlow = defineFlow({
+  name: 'showcase_task_completed_slack',
+  label: 'Post to Slack on Task Completed',
+  description: 'Posts to a Slack channel via the slack connector when a task is marked Done.',
+  type: 'autolaunched',
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'On Task Update',
+      config: {
+        objectName: 'showcase_task',
+        triggerType: 'record-after-update',
+        condition: 'status == "done" && previous.status != "done"',
+      },
+    },
+    {
+      id: 'post_to_slack',
+      type: 'connector_action',
+      label: 'Post to #wins',
+      connectorConfig: {
+        connectorId: 'slack',
+        actionId: 'chat.postMessage',
+        input: {
+          channel: 'C0WINS000',
+          text: '✅ Task done: {record.title}',
+        },
+      },
+    },
+    { id: 'end', type: 'end', label: 'End' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'post_to_slack' },
+    { id: 'e2', source: 'post_to_slack', target: 'end' },
+  ],
+});
+
+export const allFlows = [
+  TaskCompletedFlow,
+  ReassignWizardFlow,
+  BudgetApprovalFlow,
+  TaskCompletedSlackFlow,
+];
diff --git a/packages/runtime/src/http-dispatcher.test.ts b/packages/runtime/src/http-dispatcher.test.ts
@@ -150,6 +150,11 @@ describe('HttpDispatcher', () => {
                     { type: 'http_request', name: 'HTTP Request', category: 'io', paradigms: ['flow', 'workflow_rule'], source: 'builtin' },
                     { type: 'send_sms', name: 'Send SMS', category: 'io', paradigms: ['flow'], source: 'plugin' },
                 ]),
+                getConnectorDescriptors: vi.fn().mockReturnValue([
+                    { name: 'rest', label: 'REST', type: 'api', actions: [{ key: 'request', label: 'Request' }] },
+                    { name: 'slack', label: 'Slack', type: 'api', actions: [{ key: 'chat.postMessage', label: 'Post Message' }] },
+                    { name: 'pg', label: 'Postgres', type: 'database', actions: [] },
+                ]),
             };
 
             // Set up kernel services to include automation
@@ -278,6 +283,40 @@ describe('HttpDispatcher', () => {
             expect(result.response?.body?.data?.actions).toEqual([]);
             expect(result.response?.body?.data?.total).toBe(0);
         });
+
+        // ── GET /connectors — connector descriptor registry (ADR-0022) ────
+        it('should list connector descriptors via GET /connectors', async () => {
+            const result = await dispatcher.handleAutomation('connectors', 'GET', {}, { request: {} });
+            expect(result.handled).toBe(true);
+            expect(mockAutomationService.getConnectorDescriptors).toHaveBeenCalled();
+            expect(result.response?.body?.data?.total).toBe(3);
+            expect(result.response?.body?.data?.connectors.map((c: any) => c.name)).toEqual(
+                ['rest', 'slack', 'pg'],
+            );
+        });
+
+        it('must NOT let GET /connectors be shadowed by the /:name flow lookup', async () => {
+            const result = await dispatcher.handleAutomation('connectors', 'GET', {}, { request: {} });
+            expect(result.handled).toBe(true);
+            // The connector registry is returned, NOT a getFlow('connectors') result.
+            expect(mockAutomationService.getFlow).not.toHaveBeenCalled();
+            expect(result.response?.body?.data?.connectors).toBeDefined();
+        });
+
+        it('should filter GET /connectors by ?type', async () => {
+            const result = await dispatcher.handleAutomation('connectors', 'GET', {}, { request: {} }, { type: 'database' });
+            expect(result.handled).toBe(true);
+            expect(result.response?.body?.data?.total).toBe(1);
+            expect(result.response?.body?.data?.connectors[0].name).toBe('pg');
+        });
+
+        it('should return an empty registry when the service lacks getConnectorDescriptors', async () => {
+            delete mockAutomationService.getConnectorDescriptors;
+            const result = await dispatcher.handleAutomation('connectors', 'GET', {}, { request: {} });
+            expect(result.handled).toBe(true);
+            expect(result.response?.body?.data?.connectors).toEqual([]);
+            expect(result.response?.body?.data?.total).toBe(0);
+        });
     });
 
     // ═══════════════════════════════════════════════════════════════
diff --git a/packages/runtime/src/http-dispatcher.ts b/packages/runtime/src/http-dispatcher.ts
@@ -1668,6 +1668,7 @@ export class HttpDispatcher {
      * Routes:
      *   GET    /                     → listFlows
      *   GET    /actions              → getActionDescriptors (ADR-0018; ?paradigm/?source/?category filters)
+     *   GET    /connectors           → getConnectorDescriptors (ADR-0022; ?type filter)
      *   GET    /:name                → getFlow
      *   POST   /                     → createFlow (registerFlow)
      *   PUT    /:name                → updateFlow
@@ -1739,6 +1740,26 @@ export class HttpDispatcher {
             return { handled: true, response: this.success({ actions: [], total: 0 }) };
         }
 
+        // GET /connectors → list registered connector descriptors (ADR-0022).
+        // Like /actions, MUST precede the `/:name → getFlow` catch-all so a flow
+        // named "connectors" cannot shadow it. Backs the designer's
+        // `connector_action` connector/action/input pickers; the registry is
+        // empty in baseline and populated by connector plugins (e.g.
+        // @objectstack/connector-rest, @objectstack/connector-slack).
+        if (parts[0] === 'connectors' && parts.length === 1 && m === 'GET') {
+            if (typeof automationService.getConnectorDescriptors === 'function') {
+                let connectors = automationService.getConnectorDescriptors() ?? [];
+                // Optional filter mirrors the descriptor's connector type.
+                if (query?.type) {
+                    connectors = connectors.filter((c: any) => c?.type === query.type);
+                }
+                return { handled: true, response: this.success({ connectors, total: connectors.length }) };
+            }
+            // Service present but does not implement the optional method:
+            // report an empty (but valid) registry rather than a 404.
+            return { handled: true, response: this.success({ connectors: [], total: 0 }) };
+        }
+
         // Routes with :name
         if (parts.length >= 1) {
             const name = parts[0];
diff --git a/packages/services/service-automation/src/builtin/connector-nodes.test.ts b/packages/services/service-automation/src/builtin/connector-nodes.test.ts
@@ -176,4 +176,47 @@ describe('AutomationEngine connector registry', () => {
         expect(engine.getRegisteredConnectors()).not.toContain('fake');
         expect(engine.resolveConnectorAction('fake', 'echo')).toBeUndefined();
     });
+
+    it('exposes a designer-facing descriptor per connector, omitting handlers (ADR-0022)', () => {
+        engine.registerConnector(
+            {
+                name: 'fake',
+                label: 'Fake Connector',
+                type: 'api',
+                icon: 'plug',
+                authentication: { type: 'none' },
+                actions: [
+                    {
+                        key: 'echo',
+                        label: 'Echo',
+                        description: 'Echo the input back',
+                        inputSchema: { message: { type: 'string' } },
+                    },
+                ],
+            } as Connector,
+            { async echo() { return {}; } },
+        );
+
+        const descriptors = engine.getConnectorDescriptors();
+        expect(descriptors).toHaveLength(1);
+        const fake = descriptors[0];
+        expect(fake.name).toBe('fake');
+        expect(fake.label).toBe('Fake Connector');
+        expect(fake.type).toBe('api');
+        expect(fake.icon).toBe('plug');
+        expect(fake.actions).toHaveLength(1);
+        expect(fake.actions[0]).toEqual({
+            key: 'echo',
+            label: 'Echo',
+            description: 'Echo the input back',
+            inputSchema: { message: { type: 'string' } },
+            outputSchema: undefined,
+        });
+        // Handlers are runtime code, never leaked into the metadata view.
+        expect((fake as any).handlers).toBeUndefined();
+    });
+
+    it('returns an empty descriptor list when no connectors are registered', () => {
+        expect(engine.getConnectorDescriptors()).toEqual([]);
+    });
 });
diff --git a/packages/services/service-automation/src/engine.ts b/packages/services/service-automation/src/engine.ts
@@ -109,6 +109,34 @@ export interface RegisteredConnector {
     readonly handlers: Record<string, ConnectorActionHandler>;
 }
 
+/**
+ * A designer-facing view of one connector action — identity + its JSON-Schema
+ * input/output. The runtime handler is intentionally omitted; this is metadata.
+ */
+export interface ConnectorActionDescriptor {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly inputSchema?: Record<string, unknown>;
+    readonly outputSchema?: Record<string, unknown>;
+}
+
+/**
+ * A designer-facing descriptor for a registered connector: its identity plus
+ * the actions it exposes. Served by `GET /api/v1/automation/connectors` so the
+ * flow designer can populate the `connector_action` node's connector → action
+ * → input pickers (ADR-0018 §Addendum, ADR-0022). Mirrors `ActionDescriptor`'s
+ * role for node types, but for the connector registry.
+ */
+export interface ConnectorDescriptor {
+    readonly name: string;
+    readonly label: string;
+    readonly type: string;
+    readonly description?: string;
+    readonly icon?: string;
+    readonly actions: ConnectorActionDescriptor[];
+}
+
 // ─── Core Automation Engine ─────────────────────────────────────────
 
 /**
@@ -301,6 +329,30 @@ export class AutomationEngine implements IAutomationService {
         return [...this.connectors.keys()];
     }
 
+    /**
+     * Get a designer-facing descriptor for every registered connector — its
+     * identity plus the actions it exposes (input/output JSON Schema). Backs
+     * `GET /api/v1/automation/connectors` so the designer can fill the
+     * `connector_action` node's connector / action / input pickers (ADR-0022).
+     * Handlers are omitted — they are runtime code, not metadata.
+     */
+    getConnectorDescriptors(): ConnectorDescriptor[] {
+        return [...this.connectors.values()].map(({ def }) => ({
+            name: def.name,
+            label: def.label,
+            type: def.type,
+            description: def.description,
+            icon: def.icon,
+            actions: (def.actions ?? []).map((a) => ({
+                key: a.key,
+                label: a.label,
+                description: a.description,
+                inputSchema: a.inputSchema,
+                outputSchema: a.outputSchema,
+            })),
+        }));
+    }
+
     /** Get all registered node types */
     getRegisteredNodeTypes(): string[] {
         return [...this.nodeExecutors.keys()];
diff --git a/packages/services/service-automation/src/index.ts b/packages/services/service-automation/src/index.ts
@@ -9,6 +9,8 @@ export type {
     ConnectorActionHandler,
     ConnectorActionContext,
     RegisteredConnector,
+    ConnectorDescriptor,
+    ConnectorActionDescriptor,
 } from './engine.js';
 
 // Kernel plugin — seeds all built-in nodes; this is the only plugin needed for
