@erxes/api-shared 0.0.0-stage → 3.2.19-1

package/src/utils/agent-tools/manifest.ts

@@ -0,0 +1,152 @@
+import {
+  AgentProcedureMeta,
+  AgentToolDescriptor,
+  AgentToolField,
+  AgentToolManifest,
+  AgentTrpcProcedure,
+  AgentTrpcRouter,
+} from './types';
+
+// Zod internals are accessed structurally to stay agnostic to the plugin's
+// zod instance. Zod 3 exposes `_def.typeName` ('ZodObject') and `.shape`;
+// Zod 4 exposes `_zod.def.type` ('object') and `_zod.def.shape`.
+interface ZodLikeSchema {
+  _def?: { typeName?: string; type?: string; shape?: unknown };
+  _zod?: { def?: { type?: string; shape?: unknown } };
+  shape?: Record<string, ZodLikeSchema>;
+  isOptional?: () => boolean;
+}
+
+const zodTypeName = (schema: ZodLikeSchema): string | undefined =>
+  schema._def?.typeName || schema._def?.type || schema._zod?.def?.type;
+
+const isZodObject = (schema: ZodLikeSchema): boolean => {
+  const typeName = zodTypeName(schema);
+
+  return typeName === 'ZodObject' || typeName === 'object';
+};
+
+const zodShape = (schema: ZodLikeSchema): Record<string, ZodLikeSchema> => {
+  if (schema.shape && typeof schema.shape === 'object') {
+    return schema.shape;
+  }
+
+  const defShape = schema._def?.shape ?? schema._zod?.def?.shape;
+
+  if (defShape && typeof defShape === 'object') {
+    return defShape as Record<string, ZodLikeSchema>;
+  }
+
+  return {};
+};
+
+/** A field is required unless wrapped in an optional/default schema. */
+const isZodRequired = (schema: ZodLikeSchema): boolean => {
+  if (typeof schema.isOptional === 'function') {
+    return !schema.isOptional();
+  }
+
+  const typeName = zodTypeName(schema);
+
+  return typeName !== 'optional' && typeName !== 'default';
+};
+
+/** Extract flat input fields when a procedure's input parser is a Zod object. */
+const extractTrpcInputFields = (
+  proc: AgentTrpcProcedure,
+): AgentToolField[] | null => {
+  const inputSchema = proc?._def?.inputs?.[0] as ZodLikeSchema | undefined;
+
+  if (!inputSchema || typeof inputSchema !== 'object') {
+    return null;
+  }
+
+  if (!isZodObject(inputSchema)) {
+    return null; // free-form object input
+  }
+
+  return Object.entries(zodShape(inputSchema)).map(([name, schema]) => ({
+    name,
+    type: zodTypeName(schema) || 'ZodUnknown',
+    required: isZodRequired(schema),
+  }));
+};
+
+/**
+ * Build the tool descriptor for one tRPC procedure, or null when the
+ * procedure declares no agent permission — tRPC tools are admit-only via
+ * `.meta({ agent: { permission } })` so nothing is callable by default.
+ */
+const buildTrpcTool = (
+  plugin: string,
+  path: string,
+  proc: AgentTrpcProcedure,
+): AgentToolDescriptor | null => {
+  // tRPC v11 router internals: `_def.procedures` is a flat path -> procedure
+  // record; procedure type lives at `_def.type`.
+  const procDef = proc?._def;
+  const method: 'query' | 'mutation' =
+    procDef?.type === 'mutation' ? 'mutation' : 'query';
+
+  // Required curation hook: procedures opt in as agent tools via
+  // `.meta({ agent: { description, permission } })`.
+  const agentMeta = (
+    procDef?.meta as { agent?: AgentProcedureMeta } | undefined
+  )?.agent;
+
+  if (!agentMeta?.permission?.action) {
+    return null;
+  }
+
+  return {
+    id: `${plugin}.trpc.${path}`,
+    kind: 'trpc',
+    plugin,
+    module: path.split('.')[0],
+    method,
+    destructive: method === 'mutation',
+    description:
+      agentMeta.description || `Call ${plugin} tRPC procedure ${path}`,
+    inputFields: extractTrpcInputFields(proc),
+    permission: agentMeta.permission,
+    path,
+  };
+};
+
+/**
+ * Derive the agent tool manifest for a plugin. tRPC tools are emitted only
+ * for procedures declaring an agent permission; nothing else is exposed.
+ */
+export const buildAgentToolManifest = (opts: {
+  plugin: string;
+  trpcRouter?: AgentTrpcRouter;
+  exclude: string[];
+}): AgentToolManifest => {
+  const { plugin, trpcRouter, exclude } = opts;
+  const tools: AgentToolDescriptor[] = [];
+
+  const procedures: Record<string, unknown> =
+    trpcRouter?._def?.procedures || {};
+
+  for (const [path, rawProc] of Object.entries(procedures)) {
+    // tRPC internals are external to this module; entries are narrowed
+    // structurally and anything without agent metadata is dropped below.
+    const proc = rawProc as AgentTrpcProcedure;
+
+    if (proc?._def?.type === 'subscription') {
+      continue;
+    }
+
+    const tool = buildTrpcTool(plugin, path, proc);
+
+    if (tool) {
+      tools.push(tool);
+    }
+  }
+
+  /** Match a tool against the configured exclude prefixes. */
+  const isExcluded = (tool: AgentToolDescriptor): boolean =>
+    exclude.some((entry) => tool.path.startsWith(entry));
+
+  return { plugin, tools: tools.filter((tool) => !isExcluded(tool)) };
+};

package/src/utils/agent-tools/responseLimit.test.ts

@@ -0,0 +1,99 @@
+import {
+  AGENT_TOOL_DEFAULT_MAX_RESPONSE_BYTES,
+  agentToolResponseTooLargeError,
+  getAgentToolMaxResponseBytes,
+  oversizedAgentToolResultBytes,
+} from './responseLimit';
+
+describe('responseLimit', () => {
+  const ORIGINAL_ENV = process.env.AGENT_TOOLS_MAX_RESPONSE_BYTES;
+
+  afterEach(() => {
+    if (ORIGINAL_ENV === undefined) {
+      delete process.env.AGENT_TOOLS_MAX_RESPONSE_BYTES;
+    } else {
+      process.env.AGENT_TOOLS_MAX_RESPONSE_BYTES = ORIGINAL_ENV;
+    }
+  });
+
+  describe('getAgentToolMaxResponseBytes', () => {
+    it('falls back to the 64KB default when the env var is unset', () => {
+      delete process.env.AGENT_TOOLS_MAX_RESPONSE_BYTES;
+
+      expect(getAgentToolMaxResponseBytes()).toBe(
+        AGENT_TOOL_DEFAULT_MAX_RESPONSE_BYTES,
+      );
+    });
+
+    it('honors a positive numeric override', () => {
+      process.env.AGENT_TOOLS_MAX_RESPONSE_BYTES = '1024';
+
+      expect(getAgentToolMaxResponseBytes()).toBe(1024);
+    });
+
+    it.each(['abc', '0', '-5'])(
+      'falls back to the default for invalid value "%s"',
+      (value) => {
+        process.env.AGENT_TOOLS_MAX_RESPONSE_BYTES = value;
+
+        expect(getAgentToolMaxResponseBytes()).toBe(
+          AGENT_TOOL_DEFAULT_MAX_RESPONSE_BYTES,
+        );
+      },
+    );
+  });
+
+  describe('oversizedAgentToolResultBytes', () => {
+    it('returns null when the serialized result fits', () => {
+      expect(oversizedAgentToolResultBytes({ ok: true }, 1024)).toBeNull();
+    });
+
+    it('returns null when the result fits exactly', () => {
+      const result = 'x'.repeat(100);
+
+      expect(oversizedAgentToolResultBytes(result, 102)).toBeNull();
+    });
+
+    it('returns the byte size when the result exceeds the budget', () => {
+      const result = { data: new Array(1000).fill('row') };
+
+      const bytes = oversizedAgentToolResultBytes(result, 1024);
+
+      expect(bytes).toBe(Buffer.byteLength(JSON.stringify(result), 'utf8'));
+    });
+
+    it('counts multi-byte characters by UTF-8 bytes, not string length', () => {
+      const result = 'үү'.repeat(100); // 2 bytes each in UTF-8
+
+      expect(oversizedAgentToolResultBytes(result, 50)).toBe(
+        Buffer.byteLength(JSON.stringify(result), 'utf8'),
+      );
+    });
+
+    it('returns null for unserializable results instead of throwing', () => {
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+
+      expect(oversizedAgentToolResultBytes(circular, 1)).toBeNull();
+    });
+  });
+
+  describe('agentToolResponseTooLargeError', () => {
+    it('carries the code, sizes, and narrowing guidance', () => {
+      const error = agentToolResponseTooLargeError(
+        'sales.trpc.deal.find',
+        150_000,
+        65_536,
+      );
+
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error & { code?: string }).code).toBe(
+        'RESPONSE_TOO_LARGE',
+      );
+      expect(error.message).toContain('sales.trpc.deal.find');
+      expect(error.message).toContain('150000');
+      expect(error.message).toContain('65536');
+      expect(error.message).toContain('limit');
+    });
+  });
+});

package/src/utils/agent-tools/responseLimit.ts

@@ -0,0 +1,66 @@
+import { getEnv } from '../utils';
+
+/**
+ * Response-size guard for agent tool calls.
+ *
+ * A tool that answers with an unbounded payload (an open-ended `find`, a fat
+ * aggregation) stalls the agent run and freezes the chat UI while the model
+ * ingests it. Every `/agent-tools/call` result is therefore capped at a
+ * serialized byte budget — mirroring the 64KB output cap code mode already
+ * enforces — and oversized results are rejected with actionable guidance so
+ * the model retries with a narrower call instead of the platform streaming an
+ * unbounded payload.
+ */
+export const AGENT_TOOL_DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024;
+
+/**
+ * Resolve the active byte budget. `AGENT_TOOLS_MAX_RESPONSE_BYTES` overrides
+ * the 64KB default; non-numeric or non-positive values fall back to it.
+ */
+export const getAgentToolMaxResponseBytes = (): number => {
+  const raw = getEnv({ name: 'AGENT_TOOLS_MAX_RESPONSE_BYTES' });
+  const parsed = Number(raw);
+
+  return Number.isFinite(parsed) && parsed > 0
+    ? Math.floor(parsed)
+    : AGENT_TOOL_DEFAULT_MAX_RESPONSE_BYTES;
+};
+
+/**
+ * Returns the serialized UTF-8 byte size of `result` when it exceeds
+ * `maxBytes`, or null when it fits (or cannot be serialized — in which case
+ * the regular response path reports the serialization failure as before).
+ */
+export const oversizedAgentToolResultBytes = (
+  result: unknown,
+  maxBytes: number,
+): number | null => {
+  let serialized: string;
+
+  try {
+    serialized = JSON.stringify(result) ?? '';
+  } catch {
+    return null;
+  }
+
+  const bytes = Buffer.byteLength(serialized, 'utf8');
+
+  return bytes > maxBytes ? bytes : null;
+};
+
+/** Build the structured too-large error returned to the agent. */
+export const agentToolResponseTooLargeError = (
+  toolId: string,
+  resultBytes: number,
+  maxBytes: number,
+): Error =>
+  Object.assign(
+    new Error(
+      `Agent tool '${toolId}' returned ${resultBytes} bytes, exceeding the ` +
+        `${maxBytes}-byte agent tool response limit. Do not retry the same ` +
+        `call as-is: paginate with limit/skip or a cursor, tighten the ` +
+        `filter, project fewer fields, or use the matching count/findOne ` +
+        `tool instead.`,
+    ),
+    { code: 'RESPONSE_TOO_LARGE' },
+  );

package/src/utils/agent-tools/types.ts

@@ -0,0 +1,52 @@
+export interface AgentToolField {
+  name: string;
+  type: string;
+  required: boolean;
+  enumValues?: string[];
+}
+
+export interface AgentToolPermission {
+  module: string;
+  action: string;
+}
+
+export interface AgentTrpcToolDescriptor {
+  id: string; // e.g. 'sales.trpc.deal.findOne'
+  kind: 'trpc';
+  plugin: string;
+  module: string; // first tRPC path segment ('deal')
+  method: 'query' | 'mutation';
+  destructive: boolean;
+  description: string;
+  inputFields: AgentToolField[] | null; // null = free-form object input
+  permission: AgentToolPermission | null;
+  path: string; // full procedure path e.g. 'deal.findOne'
+}
+
+export type AgentToolDescriptor = AgentTrpcToolDescriptor;
+
+export interface AgentToolManifest {
+  plugin: string;
+  tools: AgentToolDescriptor[];
+}
+
+/** Optional per-procedure agent curation metadata. */
+export interface AgentProcedureMeta {
+  description?: string;
+  permission?: AgentToolPermission;
+}
+
+/** Structural view of a tRPC v11 procedure used for tool derivation. */
+export interface AgentTrpcProcedure {
+  _def?: {
+    type?: string;
+    inputs?: unknown[];
+    meta?: unknown;
+  };
+}
+
+/** Structural view of a tRPC v11 router accepted from plugins. */
+export interface AgentTrpcRouter {
+  _def?: { procedures?: Record<string, unknown> };
+  createCaller?: (context: unknown) => unknown;
+}

package/src/utils/apollo/beforeResolvers.ts

@@ -0,0 +1,117 @@
+import { initTRPC } from '@trpc/server';
+import * as trpcExpress from '@trpc/server/adapters/express';
+import { Express } from 'express';
+import { z } from 'zod';
+import { createTRPCContext } from '../trpc';
+import { initializePluginConfig } from '../service-discovery';
+
+export interface BeforeResolverParams {
+  resolver: string;
+  args?: Record<string, unknown>;
+  user?: unknown;
+  headers?: Record<string, unknown>;
+}
+
+export type BeforeResolverOkResult = {
+  status: 'ok';
+  args?: Record<string, unknown>;
+};
+
+export type BeforeResolverBlockedResult = {
+  status: 'blocked';
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+};
+
+export type BeforeResolverResolvedResult = {
+  status: 'resolved';
+  data: unknown;
+};
+
+export type BeforeResolverResult =
+  | BeforeResolverOkResult
+  | BeforeResolverBlockedResult
+  | BeforeResolverResolvedResult
+  | Record<string, unknown>
+  | null
+  | undefined;
+
+export type BeforeResolverHandler = (
+  subdomain: string,
+  params: BeforeResolverParams,
+) => Promise<BeforeResolverResult> | BeforeResolverResult;
+
+export interface BeforeResolversConfig {
+  resolvers: Record<string, string[]>;
+  handler: BeforeResolverHandler;
+  check?: BeforeResolverHandler;
+  blocker?: BeforeResolverHandler;
+}
+
+export enum TBeforeResolversProducers {
+  HANDLE = 'handle',
+  CHECK = 'check',
+  BLOCKER = 'blocker',
+}
+
+export type TBeforeResolversProducersInput = {
+  [TBeforeResolversProducers.HANDLE]: BeforeResolverParams;
+  [TBeforeResolversProducers.CHECK]: BeforeResolverParams;
+  [TBeforeResolversProducers.BLOCKER]: BeforeResolverParams;
+};
+
+const beforeResolverInput = z.object({
+  subdomain: z.string(),
+  data: z.object({
+    resolver: z.string(),
+    args: z.record(z.unknown()).optional(),
+    user: z.unknown().optional(),
+    headers: z.record(z.unknown()).optional(),
+  }),
+});
+
+export const startBeforeResolvers = async (
+  app: Express,
+  pluginName: string,
+  config: BeforeResolversConfig,
+) => {
+  const { resolvers, handler, check, blocker } = config || {};
+
+  if (!handler || !resolvers) {
+    return;
+  }
+
+  await initializePluginConfig(pluginName, 'beforeResolvers', { resolvers });
+
+  const t = initTRPC.context<{ subdomain: string }>().create();
+
+  const router = t.router({
+    handle: t.procedure
+      .input(beforeResolverInput)
+      .mutation(async ({ input }) => {
+        return await handler(input.subdomain, input.data);
+      }),
+    check: t.procedure.input(beforeResolverInput).query(async ({ input }) => {
+      if (check) {
+        return await check(input.subdomain, input.data);
+      }
+
+      return { status: 'ok' };
+    }),
+    blocker: t.procedure.input(beforeResolverInput).query(async ({ input }) => {
+      if (blocker) {
+        return await blocker(input.subdomain, input.data);
+      }
+
+      return { status: 'ok' };
+    }),
+  });
+
+  const middleware = trpcExpress.createExpressMiddleware({
+    router,
+    createContext: createTRPCContext(async (_subdomain, context) => context),
+  });
+
+  app.use('/beforeResolvers', middleware);
+};

package/src/utils/apollo/commonTypeDefs.ts

@@ -0,0 +1,78 @@
+export const graphqlAttachmentType = `
+  type Attachment {
+    url: String!
+    name: String
+    type: String
+    size: Float
+    duration: Float
+  }
+`;
+
+export const graphqlAttachmentInput = `
+  input AttachmentInput {
+    url: String!
+    name: String!
+    type: String
+    size: Float
+    duration: Float
+  }
+`;
+
+export const graphqlPdfAttachmentType = `
+  type PdfAttachment {
+    pdf: Attachment
+    pages: [Attachment]
+  }
+`;
+
+export const graphqlPdfAttachmentInput = `
+  input PdfAttachmentInput {
+    pdf: AttachmentInput
+    pages: [AttachmentInput]
+  }
+`;
+
+export const graphqlPaginationInfo = `
+  type PageInfo {
+    hasNextPage: Boolean,
+    hasPreviousPage: Boolean,
+    startCursor: String,
+    endCursor: String,
+  }
+`;
+
+export const apolloCommonTypes = `
+  scalar Date
+  scalar JSON
+
+  enum CURSOR_DIRECTION {
+    forward,
+    backward
+  }
+
+  enum CURSOR_MODE {
+    inclusive,
+    exclusive
+  }
+
+  enum CONTACT_STATUS {
+    active,
+    deleted
+  }
+
+  type Coordinate {
+    longitude: String
+    latitude: String
+  }
+
+  input CoordinateInput {
+    longitude: String
+    latitude: String
+  }
+
+  ${graphqlAttachmentType}
+  ${graphqlAttachmentInput}
+  ${graphqlPdfAttachmentType}
+  ${graphqlPdfAttachmentInput}
+  ${graphqlPaginationInfo}
+`;

package/src/utils/apollo/constants.ts

@@ -0,0 +1,16 @@
+export const GQL_CURSOR_PARAM_DEFS = `
+  limit: Int
+  cursor: String
+  cursorMode: CURSOR_MODE
+  direction: CURSOR_DIRECTION
+  orderBy: JSON
+  sortMode: String
+  aggregationPipeline: [JSON]
+`;
+
+export const GQL_OFFSET_PARAM_DEFS = `
+  page: Int
+  perPage: Int
+  sortField: String
+  sortDirection: String
+`;

package/src/utils/apollo/customScalars.ts

@@ -0,0 +1,69 @@
+import { GraphQLScalarType } from 'graphql';
+import { Kind } from 'graphql/language'; // tslint:disable-line
+
+const jsonIdentity = (value: any) => {
+  return value;
+};
+
+const jsonParseLiteral = (ast: any) => {
+  switch (ast.kind) {
+    case Kind.STRING:
+    case Kind.BOOLEAN:
+      return ast.value;
+    case Kind.INT:
+    case Kind.FLOAT:
+      return Number.parseFloat(ast.value);
+    case Kind.OBJECT: {
+      const value = Object.create(null);
+
+      ast.fields.forEach((field: any) => {
+        value[field.name.value] = jsonParseLiteral(field.value);
+      });
+
+      return value;
+    }
+    case Kind.LIST:
+      return ast.values.map(jsonParseLiteral);
+    default:
+      return null;
+  }
+};
+
+export const apolloCustomScalars = {
+  Date: new GraphQLScalarType({
+    name: 'Date',
+    description: 'Date custom scalar type',
+    parseValue(value: any) {
+      return new Date(value); // value from the client
+    },
+    serialize: (value: any) => {
+      if (value instanceof Date) {
+        return value.toISOString();
+      }
+
+      if (value.toISOString) {
+        return value.toISOString();
+      }
+
+      return new Date(value).toISOString();
+    },
+
+    parseLiteral(ast) {
+      if (ast.kind === Kind.INT) {
+        return new Date(parseInt(ast.value, 10)); // ast value is always in string format
+      }
+      return null;
+    },
+  }),
+
+  JSON: new GraphQLScalarType({
+    name: 'JSON',
+    description:
+      'The `jSON` scalar type represents jSON values as specified by ' +
+      '[ECMA-404](http://www.ecma-international.org/' +
+      'publications/files/ECMA-ST/ECMA-404.pdf).',
+    serialize: jsonIdentity,
+    parseValue: jsonIdentity,
+    parseLiteral: jsonParseLiteral,
+  }),
+};