@hashgraphonline/standards-agent-kit 0.2.162 → 0.2.165

package/src/plugins/registry-broker/RegistryBrokerOperationTool.ts

@@ -0,0 +1,630 @@
+import { z } from 'zod';
+import {
+  RegistryBrokerClient,
+  RegistryBrokerError,
+  type RegistryBrokerClientOptions,
+  type SearchParams,
+  type VectorSearchRequest,
+  type AgentRegistrationRequest,
+  type RegisterAgentOptions,
+  type LedgerChallengeRequest,
+  type LedgerVerifyRequest,
+  type LedgerCredentialAuthOptions,
+  type CreateSessionRequestPayload,
+  type SendMessageRequestPayload,
+  type CompactHistoryRequestPayload,
+  type EncryptionHandshakeSubmissionPayload,
+  type StartEncryptedChatSessionOptions,
+  type AcceptEncryptedChatSessionOptions,
+  type StartConversationOptions,
+  type AcceptConversationOptions,
+  type ChatHistoryFetchOptions,
+  type RegisterEncryptionKeyPayload,
+  type DeriveSharedSecretOptions,
+  type EncryptCipherEnvelopeOptions,
+  type DecryptCipherEnvelopeOptions,
+  type EnsureAgentKeyOptions,
+  type GenerateEncryptionKeyPairOptions,
+  type InitializeAgentClientOptions,
+  type ChatHistoryEntry,
+} from '@hashgraphonline/standards-sdk/services/registry-broker';
+import {
+  BaseHederaQueryTool,
+  type BaseHederaQueryToolParams,
+} from 'hedera-agent-kit';
+import type { RegistryBrokerClientProvider } from './RegistryBrokerClientProvider';
+import { RegistryBrokerConversationStore } from './RegistryBrokerConversationStore';
+
+const nonEmptyString = (label: string): z.ZodString =>
+  z
+    .string({
+      required_error: `${label} is required`,
+      invalid_type_error: `${label} must be a string`,
+    })
+    .min(1, `${label} cannot be empty`);
+
+const objectLike = <T>(label: string): z.ZodType<T> =>
+  z.custom<T>(
+    value => typeof value === 'object' && value !== null,
+    `${label} must be an object`,
+  );
+
+const registrySearchParamsSchema: z.ZodType<SearchParams> = z
+  .object({
+    q: z.string().optional(),
+    page: z.number().int().positive().optional(),
+    limit: z.number().int().positive().optional(),
+    registry: z.string().optional(),
+    registries: z.array(z.string()).optional(),
+    capabilities: z.array(z.string()).optional(),
+    protocols: z.array(z.string()).optional(),
+    minTrust: z.number().min(0).max(100).optional(),
+    adapters: z.array(z.string()).optional(),
+    sortBy: z.string().optional(),
+    sortOrder: z.enum(['asc', 'desc']).optional(),
+    type: z.string().optional(),
+    verified: z.boolean().optional(),
+    online: z.boolean().optional(),
+    metadata: z
+      .record(
+        z.array(z.union([z.string(), z.number(), z.boolean()])),
+      )
+      .optional(),
+  })
+  .partial();
+
+const registryBrokerInputSchema = z.object({
+  operation: z.string(),
+  payload: z.unknown().optional(),
+});
+
+type RegistryBrokerToolInput = z.infer<typeof registryBrokerInputSchema>;
+
+type OperationPath = string;
+
+type MethodOperationDefinition =
+  | { type: 'noArgs'; path: OperationPath }
+  | {
+      type: 'string';
+      path: OperationPath;
+      field: string;
+      optional?: boolean;
+    }
+  | { type: 'object'; path: OperationPath; schema: z.ZodTypeAny }
+  | {
+      type: 'tuple';
+      path: OperationPath;
+      schema: z.ZodTypeAny;
+      mapArgs: (payload: unknown) => unknown[];
+    };
+
+type CustomOperationDefinition = {
+  type: 'custom';
+  schema: z.ZodTypeAny;
+  handler: (payload: unknown) => Promise<unknown>;
+};
+
+type OperationDefinition = MethodOperationDefinition | CustomOperationDefinition;
+
+const noArgs = (path: string): MethodOperationDefinition => ({
+  type: 'noArgs',
+  path,
+});
+
+const stringArg = (
+  path: string,
+  field: string,
+  optional = false,
+): MethodOperationDefinition => ({
+  type: 'string',
+  path,
+  field,
+  optional,
+});
+
+const objectArg = (
+  path: string,
+  schema: z.ZodTypeAny,
+): MethodOperationDefinition => ({
+  type: 'object',
+  path,
+  schema,
+});
+
+const tupleArg = (
+  path: string,
+  schema: z.ZodTypeAny,
+  mapArgs: (payload: unknown) => unknown[],
+): MethodOperationDefinition => ({
+  type: 'tuple',
+  path,
+  schema,
+  mapArgs,
+});
+
+export class RegistryBrokerOperationTool extends BaseHederaQueryTool<
+  typeof registryBrokerInputSchema
+> {
+  name = 'registry_broker_operation';
+  description =
+    'Invoke registry-broker client methods (search, chat, registry lifecycle, ledger auth, encryption).';
+  namespace = 'registry-broker';
+  specificInputSchema = registryBrokerInputSchema;
+
+  constructor(
+    params: BaseHederaQueryToolParams & {
+      clientProvider: RegistryBrokerClientProvider;
+      handleStore: RegistryBrokerConversationStore;
+    },
+  ) {
+    super(params);
+    this.clientProvider = params.clientProvider;
+    this.handleStore = params.handleStore;
+  }
+
+  private readonly clientProvider: RegistryBrokerClientProvider;
+  private readonly handleStore: RegistryBrokerConversationStore;
+
+  protected override async executeQuery(
+    input: RegistryBrokerToolInput,
+  ): Promise<{
+    success: boolean;
+    operation: string;
+    result?: unknown;
+    error?: string;
+  }> {
+    try {
+      const result = await this.performOperation(input);
+      return {
+        success: true,
+        operation: input.operation,
+        result,
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : String(error ?? 'unknown error');
+      const brokerDetails =
+        error instanceof RegistryBrokerError
+          ? {
+              status: error.status,
+              statusText: error.statusText,
+              body: error.body,
+            }
+          : undefined;
+      this.logger.error?.(
+        `[RegistryBrokerPlugin] Operation "${input.operation}" failed`,
+        error,
+      );
+      return {
+        success: false,
+        operation: input.operation,
+        error: message,
+        ...(brokerDetails ? { details: brokerDetails } : {}),
+      };
+    }
+  }
+
+  private async performOperation(
+    input: RegistryBrokerToolInput,
+  ): Promise<unknown> {
+    if (CONVERSATION_OPERATIONS.has(input.operation)) {
+      return this.handleConversationOperation(input);
+    }
+    if (input.operation === 'initializeAgent') {
+      return this.handleInitializeAgent(input.payload);
+    }
+    const definition = OPERATION_DEFINITIONS[input.operation];
+    if (!definition) {
+      throw new Error(`Unsupported registry broker operation: ${input.operation}`);
+    }
+    if (definition.type === 'custom') {
+      const parsed = definition.schema.parse(input.payload);
+      return definition.handler(parsed);
+    }
+    const client = await this.clientProvider.getClient();
+    const target = this.resolveTarget(client, definition.path);
+    if (typeof target !== 'function') {
+      throw new Error(`Method "${definition.path}" is unavailable on the client`);
+    }
+    if (definition.type === 'noArgs') {
+      const result = await target.call(client);
+      return this.formatResult(input.operation, result);
+    }
+    if (definition.type === 'string') {
+      const schema = z
+        .object({
+          [definition.field]: definition.optional
+            ? z.string().optional()
+            : nonEmptyString(definition.field),
+        })
+        .strict();
+      const parsed = schema.parse(
+        definition.optional && input.payload === undefined
+          ? {}
+          : input.payload ?? {},
+      );
+      const arg = parsed[definition.field];
+      const result = await target.call(client, arg);
+      return this.formatResult(input.operation, result);
+    }
+    if (definition.type === 'object') {
+      const parsed = definition.schema.parse(
+        input.payload ?? ({} as unknown as RegistryBrokerClientOptions),
+      );
+      const result = await target.call(client, parsed);
+      return this.formatResult(input.operation, result);
+    }
+    if (definition.type === 'tuple') {
+      const parsed = definition.schema.parse(input.payload ?? {});
+      const args = definition.mapArgs(parsed);
+      const result = await target.apply(client, args);
+      return this.formatResult(input.operation, result);
+    }
+    return undefined;
+  }
+
+  private async handleConversationOperation(
+    input: RegistryBrokerToolInput,
+  ): Promise<unknown> {
+    switch (input.operation) {
+      case 'conversation.send': {
+        const parsed = conversationSendSchema.parse(input.payload ?? {});
+        const handle = this.handleStore.get(parsed.handleId);
+        return handle.send(parsed.payload);
+      }
+      case 'conversation.decryptHistoryEntry': {
+        const parsed = conversationDecryptSchema.parse(input.payload ?? {});
+        const handle = this.handleStore.get(parsed.handleId);
+        return handle.decryptHistoryEntry(parsed.entry);
+      }
+      case 'conversation.release': {
+        const parsed = conversationReleaseSchema.parse(input.payload ?? {});
+        return this.handleStore.release(parsed.handleId);
+      }
+      default:
+        throw new Error(`Unsupported conversation operation: ${input.operation}`);
+    }
+  }
+
+  private async handleInitializeAgent(payload: unknown): Promise<unknown> {
+    const parsed = initializeAgentSchema.parse(payload ?? {});
+    const result = await RegistryBrokerClient.initializeAgent(parsed);
+    return {
+      encryption: result.encryption ?? null,
+      defaultHeaders: result.client.getDefaultHeaders(),
+    };
+  }
+
+  private resolveTarget(
+    client: RegistryBrokerClient,
+    path: string,
+  ): unknown {
+    return path.split('.').reduce((acc: unknown, key) => {
+      if (acc && typeof acc === 'object') {
+        return (acc as Record<string, unknown>)[key];
+      }
+      return undefined;
+    }, client);
+  }
+
+  private formatResult(
+    operation: string,
+    result: unknown,
+  ): unknown {
+    if (this.isConversationHandle(result)) {
+      const stored = this.handleStore.register(result);
+      return {
+        handleId: stored.handleId,
+        sessionId: stored.sessionId,
+        mode: stored.mode,
+        summary: stored.summary ?? null,
+      };
+    }
+    if (operation === 'getDefaultHeaders' && typeof result === 'object') {
+      return result;
+    }
+    return result;
+  }
+
+  private isConversationHandle(
+    value: unknown,
+  ): value is Parameters<
+    RegistryBrokerConversationStore['register']
+  >[0] {
+    if (!value || typeof value !== 'object') {
+      return false;
+    }
+    const candidate = value as Record<string, unknown>;
+    return (
+      typeof candidate.sessionId === 'string' &&
+      typeof candidate.send === 'function' &&
+      typeof candidate.decryptHistoryEntry === 'function'
+    );
+  }
+}
+
+const conversationOperations = [
+  'conversation.send',
+  'conversation.decryptHistoryEntry',
+  'conversation.release',
+] as const;
+
+const CONVERSATION_OPERATIONS = new Set<string>(conversationOperations);
+
+const conversationSendSchema = z.object({
+  handleId: nonEmptyString('handleId'),
+  payload: objectLike<Parameters<
+    Parameters<RegistryBrokerConversationStore['register']>[0]['send']
+  >[0]>('payload'),
+});
+
+const conversationDecryptSchema = z.object({
+  handleId: nonEmptyString('handleId'),
+  entry: objectLike<ChatHistoryEntry>('entry'),
+});
+
+const conversationReleaseSchema = z.object({
+  handleId: nonEmptyString('handleId'),
+});
+
+const vectorSearchSchema =
+  objectLike<VectorSearchRequest>('vectorSearchRequest');
+
+const registerAgentSchema = z.object({
+  payload: objectLike<AgentRegistrationRequest>('registerAgentPayload'),
+  options: objectLike<RegisterAgentOptions>('registerAgentOptions').optional(),
+});
+
+const updateAgentSchema = z.object({
+  uaid: nonEmptyString('uaid'),
+  request: objectLike<AgentRegistrationRequest>('request'),
+});
+
+const waitForRegistrationSchema = z.object({
+  attemptId: nonEmptyString('attemptId'),
+  options: objectLike<{
+    intervalMs?: number;
+    timeoutMs?: number;
+    throwOnFailure?: boolean;
+  }>('options').optional(),
+});
+
+const registryNamespaceSchema = z.object({
+  registry: nonEmptyString('registry'),
+  namespace: nonEmptyString('namespace'),
+});
+
+const ledgerChallengeSchema =
+  objectLike<LedgerChallengeRequest>('ledgerChallenge');
+
+const ledgerVerifySchema =
+  objectLike<LedgerVerifyRequest>('ledgerVerifyRequest');
+
+const ledgerAuthSchema =
+  objectLike<LedgerCredentialAuthOptions>('ledgerCredentialAuth');
+
+const createSessionSchema =
+  objectLike<CreateSessionRequestPayload>('createSessionPayload');
+
+const sendMessageSchema =
+  objectLike<SendMessageRequestPayload>('sendMessagePayload');
+
+const chatHistorySchema = z.object({
+  sessionId: nonEmptyString('sessionId'),
+  options: objectLike<ChatHistoryFetchOptions>('historyOptions').optional(),
+});
+
+const submitHandshakeSchema = z.object({
+  sessionId: nonEmptyString('sessionId'),
+  payload: objectLike<EncryptionHandshakeSubmissionPayload>(
+    'handshakePayload',
+  ),
+});
+
+const compactHistorySchema =
+  objectLike<CompactHistoryRequestPayload>('compactHistoryPayload');
+
+const registerKeySchema =
+  objectLike<RegisterEncryptionKeyPayload>('registerEncryptionKeyPayload');
+
+const deriveSecretSchema =
+  objectLike<DeriveSharedSecretOptions>('deriveSharedSecretOptions');
+
+const encryptEnvelopeSchema =
+  objectLike<EncryptCipherEnvelopeOptions>('encryptCipherEnvelopeOptions');
+
+const decryptEnvelopeSchema =
+  objectLike<DecryptCipherEnvelopeOptions>('decryptCipherEnvelopeOptions');
+
+const ensureAgentKeySchema =
+  objectLike<EnsureAgentKeyOptions>('ensureAgentKeyOptions');
+
+const generateKeyPairSchema = z
+  .object({
+    keyType: z.enum(['secp256k1']).optional(),
+    envVar: z.string().optional(),
+    envPath: z.string().optional(),
+    overwrite: z.boolean().optional(),
+  })
+  .partial()
+  .optional();
+
+const startChatSchema =
+  objectLike<StartChatOptions>('startChatOptions');
+
+const startConversationSchema =
+  objectLike<StartConversationOptions>('startConversationOptions');
+
+const acceptConversationSchema =
+  objectLike<AcceptConversationOptions>('acceptConversationOptions');
+
+const startEncryptedSessionSchema =
+  objectLike<StartEncryptedChatSessionOptions>(
+    'startEncryptedSessionOptions',
+  );
+
+const acceptEncryptedSessionSchema =
+  objectLike<AcceptEncryptedChatSessionOptions>(
+    'acceptEncryptedSessionOptions',
+  );
+
+const initializeAgentSchema =
+  objectLike<InitializeAgentClientOptions>('initializeAgentOptions');
+
+const OPERATION_DEFINITIONS: Record<string, OperationDefinition> = {
+  stats: noArgs('stats'),
+  registries: noArgs('registries'),
+  getAdditionalRegistries: noArgs('getAdditionalRegistries'),
+  popularSearches: noArgs('popularSearches'),
+  adapters: noArgs('adapters'),
+  adaptersDetailed: noArgs('adaptersDetailed'),
+  listProtocols: noArgs('listProtocols'),
+  searchStatus: noArgs('searchStatus'),
+  websocketStats: noArgs('websocketStats'),
+  metricsSummary: noArgs('metricsSummary'),
+  dashboardStats: noArgs('dashboardStats'),
+  getX402Minimums: noArgs('getX402Minimums'),
+  encryptionReady: noArgs('encryptionReady'),
+  getDefaultHeaders: noArgs('getDefaultHeaders'),
+  setApiKey: stringArg('setApiKey', 'apiKey', true),
+  setLedgerApiKey: stringArg('setLedgerApiKey', 'apiKey', true),
+  resolveUaid: stringArg('resolveUaid', 'uaid'),
+  validateUaid: stringArg('validateUaid', 'uaid'),
+  getUaidConnectionStatus: stringArg(
+    'getUaidConnectionStatus',
+    'uaid',
+  ),
+  closeUaidConnection: stringArg('closeUaidConnection', 'uaid'),
+  facets: stringArg('facets', 'adapter', true),
+  search: objectArg('search', registrySearchParamsSchema),
+  vectorSearch: objectArg('vectorSearch', vectorSearchSchema),
+  registrySearchByNamespace: tupleArg(
+    'registrySearchByNamespace',
+    registryNamespaceSchema,
+    payload => [payload.registry, payload.namespace],
+  ),
+  registerAgent: tupleArg(
+    'registerAgent',
+    registerAgentSchema,
+    payload => [payload.payload, payload.options],
+  ),
+  getRegistrationQuote: objectArg(
+    'getRegistrationQuote',
+    objectLike<AgentRegistrationRequest>('getRegistrationQuotePayload'),
+  ),
+  updateAgent: tupleArg(
+    'updateAgent',
+    updateAgentSchema,
+    payload => [payload.uaid, payload.request],
+  ),
+  getRegistrationProgress: stringArg(
+    'getRegistrationProgress',
+    'attemptId',
+  ),
+  waitForRegistrationCompletion: tupleArg(
+    'waitForRegistrationCompletion',
+    waitForRegistrationSchema,
+    payload => [payload.attemptId, payload.options],
+  ),
+  purchaseCreditsWithHbar: objectArg(
+    'purchaseCreditsWithHbar',
+    objectLike('purchaseCreditsWithHbar'),
+  ),
+  purchaseCreditsWithX402: objectArg(
+    'purchaseCreditsWithX402',
+    objectLike('purchaseCreditsWithX402'),
+  ),
+  buyCreditsWithX402: objectArg(
+    'buyCreditsWithX402',
+    objectLike('buyCreditsWithX402'),
+  ),
+  createLedgerChallenge: objectArg(
+    'createLedgerChallenge',
+    ledgerChallengeSchema,
+  ),
+  verifyLedgerChallenge: objectArg(
+    'verifyLedgerChallenge',
+    ledgerVerifySchema,
+  ),
+  authenticateWithLedger: objectArg(
+    'authenticateWithLedger',
+    ledgerAuthSchema,
+  ),
+  authenticateWithLedgerCredentials: objectArg(
+    'authenticateWithLedgerCredentials',
+    ledgerAuthSchema,
+  ),
+  detectProtocol: objectArg('detectProtocol', objectLike('detectProtocol')),
+  setDefaultHeader: tupleArg(
+    'setDefaultHeader',
+    z.object({
+      name: nonEmptyString('name'),
+      value: z.string().optional(),
+    }),
+    payload => [payload.name, payload.value],
+  ),
+  'chat.start': objectArg('chat.start', startChatSchema),
+  'chat.createSession': objectArg('chat.createSession', createSessionSchema),
+  'chat.sendMessage': objectArg('chat.sendMessage', sendMessageSchema),
+  'chat.endSession': stringArg('chat.endSession', 'sessionId'),
+  'chat.getHistory': tupleArg('chat.getHistory', chatHistorySchema, payload => [
+    payload.sessionId,
+    payload.options,
+  ]),
+  'chat.compactHistory': objectArg(
+    'chat.compactHistory',
+    compactHistorySchema,
+  ),
+  'chat.getEncryptionStatus': stringArg(
+    'chat.getEncryptionStatus',
+    'sessionId',
+  ),
+  'chat.submitEncryptionHandshake': tupleArg(
+    'chat.submitEncryptionHandshake',
+    submitHandshakeSchema,
+    payload => [payload.sessionId, payload.payload],
+  ),
+  'chat.createEncryptedSession': objectArg(
+    'chat.createEncryptedSession',
+    startEncryptedSessionSchema,
+  ),
+  'chat.acceptEncryptedSession': objectArg(
+    'chat.acceptEncryptedSession',
+    acceptEncryptedSessionSchema,
+  ),
+  'chat.startConversation': objectArg(
+    'chat.startConversation',
+    startConversationSchema,
+  ),
+  'chat.acceptConversation': objectArg(
+    'chat.acceptConversation',
+    acceptConversationSchema,
+  ),
+  'encryption.registerKey': objectArg(
+    'encryption.registerKey',
+    registerKeySchema,
+  ),
+  'encryption.generateEphemeralKeyPair': noArgs(
+    'encryption.generateEphemeralKeyPair',
+  ),
+  'encryption.deriveSharedSecret': objectArg(
+    'encryption.deriveSharedSecret',
+    deriveSecretSchema,
+  ),
+  'encryption.encryptCipherEnvelope': objectArg(
+    'encryption.encryptCipherEnvelope',
+    encryptEnvelopeSchema,
+  ),
+  'encryption.decryptCipherEnvelope': objectArg(
+    'encryption.decryptCipherEnvelope',
+    decryptEnvelopeSchema,
+  ),
+  'encryption.ensureAgentKey': objectArg(
+    'encryption.ensureAgentKey',
+    ensureAgentKeySchema,
+  ),
+  generateEncryptionKeyPair: objectArg(
+    'generateEncryptionKeyPair',
+    generateKeyPairSchema,
+  ),
+};

package/src/plugins/registry-broker/RegistryBrokerPlugin.ts

@@ -0,0 +1,63 @@
+import {
+  BasePlugin,
+  type GenericPluginContext,
+  type HederaAgentKit,
+  type HederaTool,
+} from 'hedera-agent-kit';
+import { RegistryBrokerClientProvider } from './RegistryBrokerClientProvider';
+import type { RegistryBrokerPluginConfiguration } from './RegistryBrokerClientProvider';
+import { RegistryBrokerConversationStore } from './RegistryBrokerConversationStore';
+import { RegistryBrokerOperationTool } from './RegistryBrokerOperationTool';
+
+export interface RegistryBrokerPluginContext extends GenericPluginContext {
+  config: GenericPluginContext['config'] & {
+    registryBroker?: RegistryBrokerPluginConfiguration;
+  };
+}
+
+export class RegistryBrokerPlugin extends BasePlugin<RegistryBrokerPluginContext> {
+  id = 'registry-broker';
+  name = 'Registry Broker Plugin';
+  description =
+    'Expose RegistryBrokerClient operations to Hedera Agent Kit tools for discovery, chat, registration, and ledger auth.';
+  version = '0.1.0';
+  author = 'Hashgraph Online';
+
+  private tools: HederaTool[] = [];
+  private clientProvider?: RegistryBrokerClientProvider;
+  private readonly handleStore = new RegistryBrokerConversationStore();
+
+  override async initialize(
+    context: RegistryBrokerPluginContext,
+  ): Promise<void> {
+    await super.initialize(context);
+    const hederaKit = context.config.hederaKit as HederaAgentKit | undefined;
+    if (!hederaKit) {
+      this.context.logger.warn(
+        '[RegistryBrokerPlugin] HederaAgentKit not available; plugin initialization skipped.',
+      );
+      this.tools = [];
+      return;
+    }
+
+    const provider = new RegistryBrokerClientProvider(
+      context.config.registryBroker,
+      this.context.logger,
+    );
+    this.clientProvider = provider;
+
+    const tool = new RegistryBrokerOperationTool({
+      hederaKit,
+      logger: this.context.logger,
+      clientProvider: provider,
+      handleStore: this.handleStore,
+    });
+
+    this.tools = [tool];
+    this.context.logger.info?.('[RegistryBrokerPlugin] Initialized.');
+  }
+
+  override getTools(): HederaTool[] {
+    return this.tools;
+  }
+}