feat(workflow-executor): implement AgentPort adapter using agent-client

packages/workflow-executor/package.json

@@ -23,6 +23,7 @@
     "test": "jest"
   },
   "dependencies": {
+    "@forestadmin/agent-client": "1.4.13",
     "@langchain/core": "1.1.33",
     "zod": "4.3.6"
   }

packages/workflow-executor/src/adapters/agent-client-agent-port.ts

@@ -0,0 +1,129 @@
+import type { AgentPort } from '../ports/agent-port';
+import type { ActionRef, CollectionRef, RecordData } from '../types/record';
+import type { RemoteAgentClient, SelectOptions } from '@forestadmin/agent-client';
+
+import { RecordNotFoundError } from '../errors';
+
+function buildPkFilter(
+  primaryKeyFields: string[],
+  recordId: Array<string | number>,
+): SelectOptions['filters'] {
+  if (primaryKeyFields.length === 1) {
+    return { field: primaryKeyFields[0], operator: 'Equal', value: recordId[0] };
+  }
+
+  return {
+    aggregator: 'And',
+    conditions: primaryKeyFields.map((field, i) => ({
+      field,
+      operator: 'Equal',
+      value: recordId[i],
+    })),
+  };
+}
+
+// agent-client methods (update, relation, action) still expect the pipe-encoded string format
+function encodePk(recordId: Array<string | number>): string {
+  return recordId.map(v => String(v)).join('|');
+}
+
+function extractRecordId(
+  primaryKeyFields: string[],
+  record: Record<string, unknown>,
+): Array<string | number> {
+  return primaryKeyFields.map(field => record[field] as string | number);
+}
+
+export default class AgentClientAgentPort implements AgentPort {
+  private readonly client: RemoteAgentClient;
+  private readonly collectionRefs: Record<string, CollectionRef>;
+
+  constructor(params: {
+    client: RemoteAgentClient;
+    collectionRefs: Record<string, CollectionRef>;
+  }) {
+    this.client = params.client;
+    this.collectionRefs = params.collectionRefs;
+  }
+
+  async getRecord(collectionName: string, recordId: Array<string | number>): Promise<RecordData> {
+    const ref = this.getCollectionRef(collectionName);
+    const records = await this.client.collection(collectionName).list<Record<string, unknown>>({
+      filters: buildPkFilter(ref.primaryKeyFields, recordId),
+      pagination: { size: 1, number: 1 },
+    });
+
+    if (records.length === 0) {
+      throw new RecordNotFoundError(collectionName, encodePk(recordId));
+    }
+
+    return { ...ref, recordId, values: records[0] };
+  }
+
+  async updateRecord(
+    collectionName: string,
+    recordId: Array<string | number>,
+    values: Record<string, unknown>,
+  ): Promise<RecordData> {
+    const ref = this.getCollectionRef(collectionName);
+    const updatedRecord = await this.client
+      .collection(collectionName)
+      .update<Record<string, unknown>>(encodePk(recordId), values);
+
+    return { ...ref, recordId, values: updatedRecord };
+  }
+
+  async getRelatedData(
+    collectionName: string,
+    recordId: Array<string | number>,
+    relationName: string,
+  ): Promise<RecordData[]> {
+    const relatedRef = this.getCollectionRef(relationName);
+
+    const records = await this.client
+      .collection(collectionName)
+      .relation(relationName, encodePk(recordId))
+      .list<Record<string, unknown>>();
+
+    return records.map(record => ({
+      ...relatedRef,
+      recordId: extractRecordId(relatedRef.primaryKeyFields, record),
+      values: record,
+    }));
+  }
+
+  async getActions(collectionName: string): Promise<ActionRef[]> {
+    const ref = this.collectionRefs[collectionName];
+
+    return ref ? ref.actions : [];
+  }
+
+  async executeAction(
+    collectionName: string,
+    actionName: string,
+    recordIds: Array<string | number>[],
+  ): Promise<unknown> {
+    const encodedIds = recordIds.map(id => encodePk(id));
+    const action = await this.client
+      .collection(collectionName)
+      .action(actionName, { recordIds: encodedIds });
+
+    return action.execute();
+  }
+
+  private getCollectionRef(collectionName: string): CollectionRef {
+    const ref = this.collectionRefs[collectionName];
+
+    if (!ref) {
+      return {
+        collectionName,
+        collectionDisplayName: collectionName,
+        primaryKeyFields: ['id'],
+        fields: [],
+        actions: [],
+      };
+    }
+
+    return ref;
+  }
+}

packages/workflow-executor/src/errors.ts

@@ -21,3 +21,9 @@ export class MalformedToolCallError extends WorkflowExecutorError {
     this.toolName = toolName;
   }
 }
+
+export class RecordNotFoundError extends WorkflowExecutorError {
+  constructor(collectionName: string, recordId: string) {
+    super(`Record not found: collection "${collectionName}", id "${recordId}"`);
+  }
+}

packages/workflow-executor/src/index.ts

@@ -19,7 +19,7 @@ export type {
   StepExecutionData,
 } from './types/step-execution-data';
 
-export type { RecordFieldRef, RecordRef, RecordData } from './types/record';
+export type { RecordFieldRef, ActionRef, CollectionRef, RecordData } from './types/record';
 
 export type {
   StepRecord,
@@ -33,6 +33,12 @@ export type { AgentPort } from './ports/agent-port';
 export type { McpConfiguration, WorkflowPort } from './ports/workflow-port';
 export type { RunStore } from './ports/run-store';
 
-export { WorkflowExecutorError, MissingToolCallError, MalformedToolCallError } from './errors';
+export {
+  WorkflowExecutorError,
+  MissingToolCallError,
+  MalformedToolCallError,
+  RecordNotFoundError,
+} from './errors';
 export { default as BaseStepExecutor } from './executors/base-step-executor';
 export { default as ConditionStepExecutor } from './executors/condition-step-executor';
+export { default as AgentClientAgentPort } from './adapters/agent-client-agent-port';

packages/workflow-executor/src/ports/agent-port.ts

@@ -1,19 +1,23 @@
 /** @draft Types derived from the workflow-executor spec -- subject to change. */
 
-import type { RecordData } from '../types/record';
+import type { ActionRef, RecordData } from '../types/record';
 
 export interface AgentPort {
-  getRecord(collectionName: string, recordId: string): Promise<RecordData>;
+  getRecord(collectionName: string, recordId: Array<string | number>): Promise<RecordData>;
   updateRecord(
     collectionName: string,
-    recordId: string,
+    recordId: Array<string | number>,
     values: Record<string, unknown>,
   ): Promise<RecordData>;
   getRelatedData(
     collectionName: string,
-    recordId: string,
+    recordId: Array<string | number>,
     relationName: string,
   ): Promise<RecordData[]>;
-  getActions(collectionName: string): Promise<string[]>;
-  executeAction(collectionName: string, actionName: string, recordIds: string[]): Promise<unknown>;
+  getActions(collectionName: string): Promise<ActionRef[]>;
+  executeAction(
+    collectionName: string,
+    actionName: string,
+    recordIds: Array<string | number>[],
+  ): Promise<unknown>;
 }

packages/workflow-executor/src/ports/workflow-port.ts

@@ -1,7 +1,7 @@
 /** @draft Types derived from the workflow-executor spec -- subject to change. */
 
 import type { PendingStepExecution } from '../types/execution';
-import type { RecordRef } from '../types/record';
+import type { CollectionRef } from '../types/record';
 import type { StepHistory } from '../types/step-history';
 
 /** Placeholder -- will be typed as McpConfiguration from @forestadmin/ai-proxy/mcp-client once added as dependency. */
@@ -10,6 +10,6 @@ export type McpConfiguration = unknown;
 export interface WorkflowPort {
   getPendingStepExecutions(): Promise<PendingStepExecution[]>;
   completeStepExecution(runId: string, stepHistory: StepHistory): Promise<void>;
-  getCollectionRef(collectionName: string): Promise<RecordRef>;
+  getCollectionRef(collectionName: string): Promise<CollectionRef>;
   getMcpServerConfigs(): Promise<McpConfiguration[]>;
 }

packages/workflow-executor/src/types/execution.ts

@@ -1,6 +1,6 @@
 /** @draft Types derived from the workflow-executor spec -- subject to change. */
 
-import type { RecordRef } from './record';
+import type { CollectionRef } from './record';
 import type { StepDefinition } from './step-definition';
 import type { StepHistory } from './step-history';
 import type { AgentPort } from '../ports/agent-port';
@@ -20,7 +20,7 @@ export interface PendingStepExecution {
   readonly step: StepDefinition;
   readonly stepHistory: StepHistory;
   readonly previousSteps: ReadonlyArray<StepRecord>;
-  readonly availableRecords: ReadonlyArray<RecordRef>;
+  readonly availableRecords: ReadonlyArray<CollectionRef>;
   readonly userInput?: UserInput;
 }
 

packages/workflow-executor/src/types/record.ts

@@ -8,13 +8,20 @@ export interface RecordFieldRef {
   referencedCollectionName?: string;
 }
 
-export interface RecordRef {
-  recordId: string;
+export interface ActionRef {
+  name: string;
+  displayName: string;
+}
+
+export interface CollectionRef {
   collectionName: string;
   collectionDisplayName: string;
+  primaryKeyFields: string[];
   fields: RecordFieldRef[];
+  actions: ActionRef[];
 }
 
-export interface RecordData extends RecordRef {
+export interface RecordData extends CollectionRef {
+  recordId: Array<string | number>;
   values: Record<string, unknown>;
 }

packages/workflow-executor/src/types/step-execution-data.ts

@@ -1,6 +1,6 @@
 /** @draft Types derived from the workflow-executor spec -- subject to change. */
 
-import type { RecordRef } from './record';
+import type { CollectionRef } from './record';
 
 interface BaseStepExecutionData {
   stepIndex: number;
@@ -17,7 +17,7 @@ export interface AiTaskStepExecutionData extends BaseStepExecutionData {
   executionParams?: Record<string, unknown>;
   executionResult?: Record<string, unknown>;
   toolConfirmationInterruption?: Record<string, unknown>;
-  selectedRecordRef?: RecordRef;
+  selectedRecord?: CollectionRef;
 }
 
 export type StepExecutionData = ConditionStepExecutionData | AiTaskStepExecutionData;