@dxos/plugin-automation 0.7.4-staging.f7e8224 → 0.7.5-labs.071a3e2

package/src/tools/openapi.ts

@@ -0,0 +1,331 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import jsonpointer from 'jsonpointer';
+import { type OpenAPIV2, type OpenAPIV3_1 } from 'openapi-types';
+
+import { ToolResult, type Tool } from '@dxos/artifact';
+import { JsonSchemaType, normalizeSchema, S, toEffectSchema } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { deepMapValues } from '@dxos/util';
+
+import type { ApiAuthorization, ServiceType } from '../types';
+
+export type CreateToolsFromApiOptions = {
+  authorization?: ApiAuthorization;
+  instructions?: string;
+};
+
+export const createToolsFromService = async (service: ServiceType): Promise<Tool[]> => {
+  invariant(service.interfaces?.length === 1 && service.interfaces[0].kind === 'api');
+  const iface = service.interfaces[0];
+  invariant(iface.schemaUrl);
+  invariant(iface.schemaUrl);
+  return createToolsFromApi(iface.schemaUrl, { authorization: iface.authorization });
+};
+
+export const createToolsFromApi = async (url: string, options?: CreateToolsFromApiOptions): Promise<Tool[]> => {
+  const res = await fetch(url);
+  const spec = (await res.json()) as OpenAPIV2.Document;
+  log('spec', { spec });
+
+  const tools: Tool[] = [];
+  for (const [path, pathItem] of Object.entries(spec.paths)) {
+    if (typeof pathItem !== 'object') {
+      continue;
+    }
+
+    // TODO(burdon): ???
+    const { ...methods } = pathItem;
+    for (const [method, m] of Object.entries(methods)) {
+      const methodItem: OpenAPIV2.OperationObject = m as OpenAPIV2.OperationObject;
+      log('methodItem', { path, method, methodItem });
+
+      const parametersResolved: OpenAPIV2.ParameterObject[] =
+        methodItem.parameters?.map((parameter: any) => {
+          const resolved = resolveJsonSchema(parameter, spec);
+          return resolved;
+        }) ?? [];
+
+      const inputSchema: JsonSchemaType = {
+        type: 'object',
+        properties: {},
+      };
+
+      const endpointParameters: OpenAPIV2.ParameterObject[] = [];
+      for (const parameter of parametersResolved) {
+        log('parameter', { parameter });
+
+        if (
+          options?.authorization?.type === 'api-key' &&
+          options.authorization.placement.type === 'query' &&
+          parameter.in === 'query' &&
+          parameter.name === options.authorization.placement.name
+        ) {
+          continue;
+        }
+
+        endpointParameters.push(parameter);
+
+        if (parameter.schema) {
+          inputSchema.properties![parameter.name] = normalizeSchema(parameter.schema);
+        } else if (typeof parameter.type === 'string') {
+          const { name, in: _in, required, ...schema } = parameter;
+          inputSchema.properties![name] = normalizeSchema(schema);
+          if (required) {
+            inputSchema.required ??= [];
+            inputSchema.required!.push(name);
+          }
+        }
+      }
+
+      log('inputSchema', { inputSchema });
+      S.validateSync(JsonSchemaType)(inputSchema);
+
+      const description = methodItem.description ?? methodItem.summary;
+      if (!description) {
+        log.warn('no description', { path, method });
+        continue;
+      }
+
+      const endpoint: EndpointDescriptor = {
+        document: spec,
+        path,
+        method,
+        parameters: endpointParameters,
+        authorization: options?.authorization,
+      };
+
+      tools.push({
+        name: getToolName(path, method, methodItem),
+        description: options?.instructions ? `${options.instructions}\n\n${description}` : description,
+        parameters: inputSchema,
+        execute: async (input) => {
+          const response = await callApiEndpoint(endpoint, input);
+          return ToolResult.Success(response);
+        },
+      });
+    }
+  }
+
+  return tools;
+};
+
+const getToolName = (path: string, method: string, methodItem: OpenAPIV2.OperationObject) => {
+  if (methodItem.operationId) {
+    return methodItem.operationId;
+  }
+
+  // Generate a name from the path and method.
+  let name = `${method.toLowerCase()}_${path.replaceAll(/[{}/]/g, '_')}`;
+  while (name.length > MAX_TOOL_NAME_LENGTH) {
+    const lengthBefore = name.length;
+
+    for (const word of GENERIC_WORDS) {
+      if (name.includes(word)) {
+        name = name.replace(word, '');
+        break;
+      }
+    }
+    name = name.replaceAll('__', '_').replace(/_$/, '');
+
+    const lengthAfter = name.length;
+    if (lengthBefore === lengthAfter) {
+      break;
+    }
+  }
+  name = name.replaceAll('__', '_').replace(/_$/, '').replace(/^_/, '');
+
+  return name.slice(0, MAX_TOOL_NAME_LENGTH);
+};
+
+const MAX_TOOL_NAME_LENGTH = 64;
+const GENERIC_WORDS = [
+  'services',
+  'service',
+  'api',
+  'rest',
+  'endpoint',
+  'get',
+  'post',
+  'put',
+  'delete',
+  'patch',
+  'head',
+  'options',
+  'trace',
+  'service',
+  'api',
+  'endpoint',
+];
+
+type EndpointDescriptor = {
+  document: OpenAPIV3_1.Document | OpenAPIV2.Document;
+  path: string;
+  method: string;
+  parameters: OpenAPIV2.ParameterObject[];
+  authorization?: ApiAuthorization;
+};
+
+const callApiEndpoint = async (endpoint: EndpointDescriptor, input: any) => {
+  log.info('endpoint', { method: endpoint.method, name: endpoint.path, input });
+
+  let url = getEndpointUrl(endpoint);
+  const request: RequestInit = {
+    method: endpoint.method,
+    headers: {},
+  };
+  const query = new URLSearchParams();
+  let body: any;
+  for (const parameter of endpoint.parameters) {
+    if (input[parameter.name] === undefined) {
+      continue;
+    }
+
+    switch (parameter.in) {
+      case 'header': {
+        if (parameter.example) {
+          (request.headers as any)[parameter.name] = parameter.default;
+        }
+        break;
+      }
+      case 'path': {
+        url = url.replace(`{${parameter.name}}`, encodeURIComponent(input[parameter.name]));
+        break;
+      }
+      case 'body': {
+        const value = input[parameter.name];
+
+        // Client-side validation
+        const effectSchema = toEffectSchema(parameter.schema);
+        S.validateSync(effectSchema)(value);
+
+        if (body) {
+          throw new Error(`Duplicate body parameter: ${parameter.name}`);
+        }
+        body = value;
+        break;
+      }
+      case 'query': {
+        query.set(parameter.name, input[parameter.name]);
+        break;
+      }
+    }
+  }
+
+  if (
+    (endpoint.authorization?.type === 'api-key' && endpoint.authorization.placement.type === 'authorization-header') ||
+    endpoint.authorization?.type === 'oauth'
+  ) {
+    (request.headers as any).Authorization = await resolveAuthorization(endpoint.authorization);
+  } else if (endpoint.authorization?.type === 'api-key' && endpoint.authorization.placement.type === 'query') {
+    query.set(endpoint.authorization.placement.name, endpoint.authorization.key);
+  }
+
+  if (query.size > 0) {
+    url += `?${query.toString()}`;
+  }
+
+  if (body) {
+    request.body = JSON.stringify(body);
+    (request.headers as any)['Content-Type'] = 'application/json';
+  }
+
+  log.info('request', { url, request });
+  const response = await fetch(url, request);
+
+  log.info('response', { ok: response.ok, status: response.status, statusText: response.statusText });
+
+  if (response.ok) {
+    const contentType = response.headers.get('Content-Type');
+    if (contentType?.includes('application/json')) {
+      return await response.json();
+    } else {
+      return await response.text();
+    }
+  } else {
+    if (response.headers.get('Content-Type')?.includes('application/json')) {
+      const responseBody = await response.text();
+      let error: any;
+      try {
+        error = JSON.parse(responseBody);
+      } catch {
+        error = responseBody;
+      }
+      log.error('error', { error });
+      throw new Error(error.message);
+    } else {
+      const error = await response.text();
+      log.error('error', { error });
+      throw new Error(error);
+    }
+  }
+};
+
+const getEndpointUrl = (endpoint: EndpointDescriptor) => {
+  let url = '';
+  if (isV3_1(endpoint.document) && endpoint.document.servers && endpoint.document.servers.length > 0) {
+    url = endpoint.document.servers[0].url;
+  } else {
+    invariant(!isV3_1(endpoint.document));
+    url = `${endpoint.document.schemes?.[0] ?? 'https'}://${endpoint.document.host}`;
+  }
+
+  if (!isV3_1(endpoint.document) && endpoint.document.basePath) {
+    url += endpoint.document.basePath;
+  }
+
+  url += endpoint.path;
+
+  return url;
+};
+
+export const resolveAuthorization = async (authorization: ApiAuthorization): Promise<string> => {
+  switch (authorization.type) {
+    case 'api-key': {
+      invariant(authorization.placement.type === 'authorization-header');
+      return `Bearer ${authorization.key}`;
+    }
+    case 'oauth': {
+      const response = await fetch(authorization.tokenUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: `grant_type=${authorization.grantType}&client_id=${authorization.clientId}&client_secret=${authorization.clientSecret}`,
+      });
+      const data = await response.json();
+      return `Bearer ${data.access_token}`;
+    }
+    default: {
+      throw new Error(`Unknown authorization type: ${(authorization as any).type}`);
+    }
+  }
+};
+
+/**
+ * Resolves all $ref properties in a JSON schema.
+ * Doesn't assume the structure of the schema.
+ * The function looks from $ref properties in the schema and resolves them to their values in the base object.
+ */
+const resolveJsonSchema = (schema: any, base: any) => {
+  return deepMapValues(schema, (value, recurse) => {
+    if (typeof value === 'object' && value !== null && '$ref' in value && typeof value.$ref === 'string') {
+      if (value.$ref.startsWith('#')) {
+        const resolved = jsonpointer.get(base, value.$ref.slice(1));
+        if (resolved) {
+          return recurse(resolved);
+        } else {
+          log.warn('unresolved', { ref: value.$ref, base });
+        }
+      }
+    }
+    return recurse(value);
+  });
+};
+
+const isV3_1 = (document: OpenAPIV3_1.Document | OpenAPIV2.Document): document is OpenAPIV3_1.Document => {
+  return (document as any).openapi === '3.0.1';
+};

package/src/translations.ts

@@ -3,10 +3,14 @@
 //
 
 import { AUTOMATION_PLUGIN } from './meta';
+import { AIChatType } from './types';
 
 export default [
   {
     'en-US': {
+      [AIChatType.typename]: {
+        'typename label': 'AI Chat',
+      },
       [AUTOMATION_PLUGIN]: {
         'plugin name': 'Automation',
         'object placeholder': 'New prompt',
@@ -18,10 +22,16 @@ export default [
         'value placeholder': 'Enter value...',
         'select preset template placeholder': 'Select preset',
         'open automation panel label': 'Show Automations',
+        'automation panel label': 'Automations',
+        'service registry label': 'Service Registry',
+
+        'chat input placeholder': 'Ask a question...',
+        'chat stop': 'Cancel request.',
 
         'function select label': 'Function',
         'function select placeholder': 'Select function',
         'function enabled': 'Enabled',
+
         'trigger select label': 'Trigger',
         'trigger select placeholder': 'Trigger type',
 
@@ -29,14 +39,19 @@ export default [
         'trigger type webhook': 'Webhook',
         'trigger type websocket': 'Websocket',
         'trigger type subscription': 'Subscription',
+        'trigger type email': 'Email',
 
         'trigger filter': 'Filter',
         'trigger cron': 'Cron',
         'trigger method': 'Method',
         'trigger endpoint': 'Endpoint',
 
-        'open assistant panel label': 'Show Assistant',
-        'assistant panel label': 'Assistant',
+        'trigger copy url': 'Copy URL',
+        'trigger copy email': 'Copy Email',
+
+        'trigger meta add': 'Add',
+        'trigger meta remove': 'Remove',
+        'trigger meta prop name placeholder': 'New meta property name',
       },
     },
   },

package/src/types/index.ts

@@ -2,5 +2,6 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './registry';
 export * from './schema';
 export * from './types';

package/src/types/registry.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ServiceType } from './schema';
+
+export type ServiceQuery = {
+  name?: string;
+  category?: string;
+};
+
+export interface BaseServiceRegistry {
+  queryServices(query?: ServiceQuery): Promise<ServiceType[]>;
+}
+
+export const categoryIcons: Record<string, string> = {
+  finance: 'ph--bank--regular',
+  health: 'ph--heart--regular',
+  geolocation: 'ph--globe-simple--regular',
+  education: 'ph--books--regular',
+  entertainment: 'ph--music-notes--regular',
+  shopping: 'ph--shopping-cart--regular',
+  travel: 'ph--airplane-takeoff--regular',
+  utilities: 'ph--lightning--regular',
+  weather: 'ph--cloud-rain--regular',
+} as const;

package/src/types/schema.ts

@@ -2,7 +2,9 @@
 // Copyright 2024 DXOS.org
 //
 
-import { ref, S, TypedObject } from '@dxos/echo-schema';
+import { ComputeGraph } from '@dxos/conductor';
+import { Expando, Ref, S, TypedObject, type Ref$ } from '@dxos/echo-schema';
+import { FunctionType } from '@dxos/functions';
 
 // TODO(burdon): Change to S.Literal (and discriminated union).
 export enum ChainInputType {
@@ -34,5 +36,97 @@ export class ChainPromptType extends TypedObject({ typename: 'dxos.org/type/Chai
 
 export class ChainType extends TypedObject({ typename: 'dxos.org/type/Chain', version: '0.1.0' })({
   name: S.optional(S.String),
-  prompts: S.optional(S.mutable(S.Array(ref(ChainPromptType)))),
+  prompts: S.optional(S.mutable(S.Array(Ref(ChainPromptType)))),
+}) {}
+
+export class AIChatType extends TypedObject({ typename: 'dxos.org/type/AIChat', version: '0.1.0' })({
+  name: S.optional(S.String),
+  // TODO(wittjosiah): Should be a ref to a Queue.
+  queue: Ref(Expando),
+}) {}
+
+const ApiAuthorizationKey = S.Struct({
+  type: S.Literal('api-key'),
+  key: S.String,
+  placement: S.Union(
+    S.Struct({
+      type: S.Literal('authorization-header'),
+    }),
+    S.Struct({
+      type: S.Literal('query'),
+      name: S.String,
+    }),
+  ),
+});
+
+const ApiAuthorizationOauth = S.Struct({
+  type: S.Literal('oauth'),
+  clientId: S.String,
+  clientSecret: S.String,
+  tokenUrl: S.String,
+  grantType: S.String,
+});
+
+export const ApiAuthorization = S.Union(ApiAuthorizationKey, ApiAuthorizationOauth);
+export type ApiAuthorization = S.Schema.Type<typeof ApiAuthorization>;
+
+const ServiceInterfaceFunction = S.Struct({
+  kind: S.Literal('function'),
+  fn: Ref(FunctionType) as Ref$<FunctionType>,
+});
+
+const ServiceInterfaceWorkflow = S.Struct({
+  kind: S.Literal('workflow'),
+  workflow: Ref(ComputeGraph) as Ref$<ComputeGraph>,
+});
+
+const ServiceInterfaceApi = S.Struct({
+  kind: S.Literal('api'),
+
+  /**
+   * URL to fetch the openapi schema.
+   */
+  schemaUrl: S.optional(S.String),
+
+  /**
+   * Inlined openapi schema.
+   */
+  schema: S.optional(S.Any),
+
+  /**
+   * Authorization configuration if required.
+   */
+  authorization: S.optional(ApiAuthorization),
+});
+
+const ServiceInterface = S.Union(ServiceInterfaceFunction, ServiceInterfaceWorkflow, ServiceInterfaceApi);
+export type ServiceInterface = S.Schema.Type<typeof ServiceInterface>;
+
+// export const ServiceType = S.Struct({
+//   serviceId: S.String,
+//   name: S.optional(S.String),
+//   description: S.optional(S.String),
+//   category: S.optional(S.String),
+//   enabled: S.optional(S.Boolean),
+
+//   /**
+//    * Entries exposed: functions, workflows, and APIs.
+//    */
+//   interfaces: S.optional(S.Array(ServiceInterface)),
+// }).pipe(EchoObject('dxos.org/type/Service', '0.1.0'));
+// dxn:type:dxos.org/type/Service
+
+// export type ServiceType = S.Schema.Type<typeof ServiceType>;
+
+export class ServiceType extends TypedObject({ typename: 'dxos.org/type/ServiceType', version: '0.1.0' })({
+  serviceId: S.String,
+  name: S.optional(S.String),
+  description: S.optional(S.String),
+  category: S.optional(S.String),
+  enabled: S.optional(S.Boolean),
+
+  /**
+   * Entries exposed: functions, workflows, and APIs.
+   */
+  interfaces: S.optional(S.Array(ServiceInterface)),
 }) {}

package/src/types/types.ts

@@ -1,27 +1,21 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-import type {
-  GraphBuilderProvides,
-  IntentResolverProvides,
-  MetadataRecordsProvides,
-  SurfaceProvides,
-  TranslationsProvides,
-} from '@dxos/app-framework';
-import { type PanelProvides } from '@dxos/plugin-deck/types';
-import { type SchemaProvides } from '@dxos/plugin-space';
+import { S } from '@dxos/echo-schema';
 
-// import { AUTOMATION_PLUGIN } from '../meta';
+import { AIChatType } from './schema';
+import { AUTOMATION_PLUGIN } from '../meta';
 
-// const AUTOMATION_ACTION = `${AUTOMATION_PLUGIN}/action`;
+export namespace AutomationAction {
+  const AUTOMATION_ACTION = `${AUTOMATION_PLUGIN}/action`;
 
-export enum AutomationAction {}
-
-export type AutomationPluginProvides = SurfaceProvides &
-  IntentResolverProvides &
-  MetadataRecordsProvides &
-  TranslationsProvides &
-  GraphBuilderProvides &
-  SchemaProvides &
-  PanelProvides;
+  export class Create extends S.TaggedClass<Create>()(`${AUTOMATION_ACTION}/create`, {
+    input: S.Struct({
+      name: S.optional(S.String),
+    }),
+    output: S.Struct({
+      object: AIChatType,
+    }),
+  }) {}
+}