@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.3

package/src/transport/BrokerMessageBuilder.js

@@ -0,0 +1,377 @@
+// BrokerMessageBuilder.js
+// ESM module
+// A tiny, zero‑dependency helper to build JSON‑RPC messages that "speak"
+// to the broker. Method names default to the current broker handlers but
+// can be reconfigured if/when you rename them.
+//
+// Public API:
+//   - IdFactory, newRequestId
+//   - toBase64Der (SPKI) + internal signing helper for authenticate
+//   - Broker (hello/auth/register/ping/list/callAbility/abilityResult/agentAbility)
+//   - MCP (subset; optional for the WS <-> stdio bridge)
+//   - configureMethods(overrides) to swap JSON‑RPC method strings
+//
+// Example:
+//   import BrokerMessageBuilder, { Broker, IdFactory } from './BrokerMessageBuilder.js';
+//   const ids = new IdFactory();
+//   ws.send(Broker.hello({ role: 'agent' }).id(ids.next()).toString());
+//   ws.send(Broker.authenticate({...}).id(ids.next()).toString());
+//   ws.send(Broker.registerCapabilities({...}).id(ids.next()).toString());
+//   ws.send(Broker.callAbility({ toolName: 'echoC', args: { message: 'hi' } }).id(ids.next()).toString());
+//   ws.send(Broker.abilityResult({ requestId, toSessionId, result: {...} }).toString());
+
+import crypto from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+
+/** @typedef {import('node:crypto').KeyObject} KeyObject */
+
+/** Central method-name map (override via configureMethods). */
+const methodNames = {
+  hello: 'kadi.hello',
+  authenticate: 'kadi.authenticate',
+  registerCapabilities: 'kadi.register_capabilities',
+  ping: 'kadi.ping',
+  listTools: 'kadi.list_tools',
+  callAbility: 'agent.callAbility',
+  abilityResult: 'ability.result'
+};
+
+/** Allow consumers to override one or more JSON‑RPC method strings. */
+export function configureMethods(overrides = {}) {
+  for (const [k, v] of Object.entries(overrides)) {
+    if (!(k in methodNames)) throw new Error(`Unknown method key: ${k}`);
+    if (typeof v !== 'string' || !v.length)
+      throw new Error(`Bad method string for ${k}`);
+    methodNames[k] = v;
+  }
+  return { ...methodNames };
+}
+
+/** Minimal JSON-RPC 2.0 message wrapper with a chainable API. */
+class JsonRpcBuilder {
+  /**
+   * @param {string} method
+   * @param {object|undefined} params
+   * @param {boolean} isNotification - when true, no id will be set unless forced via .id()
+   */
+  constructor(method, params = undefined, isNotification = false) {
+    this._jsonrpc = '2.0';
+    this._method = method;
+    this._params = params;
+    this._id = isNotification ? undefined : 0; // placeholder until .id()
+    this._forceNoId = isNotification;
+  }
+
+  /** Attach/override params. */
+  params(obj) {
+    this._params = obj ?? undefined;
+    return this;
+  }
+
+  /** Set the JSON-RPC id (number|string). If null/undefined, remove id (notification). */
+  id(id) {
+    this._id = id ?? undefined;
+    this._forceNoId = id == null;
+    return this;
+  }
+
+  /** Build a plain object suitable for JSON.stringify and sending. */
+  build() {
+    /** @type {any} */
+    const msg = { jsonrpc: this._jsonrpc, method: this._method };
+    if (this._params !== undefined) msg.params = this._params;
+    if (!this._forceNoId) {
+      msg.id = this._id === 0 ? IdFactory.default().next() : this._id;
+    }
+    return msg;
+  }
+
+  /** Convenience: JSON string. */
+  toString() {
+    return JSON.stringify(this.build());
+  }
+}
+
+/** Monotonic id generator; stable across builders if you reuse the instance. */
+export class IdFactory {
+  constructor(prefix = '') {
+    this.prefix = prefix;
+    this.counter = 1;
+  }
+  next() {
+    const n = this.counter++;
+    return this.prefix ? `${this.prefix}${n}` : n;
+  }
+  static default() {
+    if (!globalThis.__brokerIdFactory)
+      globalThis.__brokerIdFactory = new IdFactory();
+    return globalThis.__brokerIdFactory;
+  }
+}
+
+/** Generate a correlation id suitable for broker requestId fields. */
+export function newRequestId() {
+  return randomUUID();
+}
+
+/**
+ * Convert a Node KeyObject public key (Ed25519) to base64 DER (SPKI) string.
+ * @param {KeyObject} pubKey
+ */
+export function toBase64Der(pubKey) {
+  return pubKey.export({ format: 'der', type: 'spki' }).toString('base64');
+}
+
+/**
+ * Build signature for authenticate. If signatureBase64 is given, returns it as-is.
+ * Otherwise, signs the nonce with the provided privateKey using Ed25519.
+ *
+ * @param {object} opts
+ * @param {string} [opts.signatureBase64]
+ * @param {KeyObject} [opts.privateKey]
+ * @param {string} opts.nonce
+ */
+function ensureSignature({ signatureBase64, privateKey, nonce }) {
+  if (signatureBase64) return signatureBase64;
+  if (!privateKey)
+    throw new Error('Either signatureBase64 or privateKey must be provided');
+  return crypto
+    .sign(null, Buffer.from(nonce, 'utf8'), privateKey)
+    .toString('base64');
+}
+
+/** Namespace: Broker protocol message builders (outbound). */
+export const Broker = {
+  /**
+   * hello — specify the role explicitly.
+   * @param {object} opts
+   * @param {'agent'|'ability'|'observer'} opts.role
+   * @param {string} [opts.version='0.1']
+   */
+  hello({ role, version = '0.1' } = {}) {
+    if (!role)
+      throw new Error('role is required ("agent" | "ability" | "observer")');
+    return new JsonRpcBuilder(methodNames.hello, { role, version });
+  },
+
+  /**
+   * authenticate
+   * @param {object} opts
+   * @param {string} opts.publicKeyBase64Der - base64 DER (SPKI) public key
+   * @param {string} opts.nonce
+   * @param {boolean} [opts.wantNewId=true]
+   * @param {KeyObject} [opts.privateKey] - used to compute signature if signatureBase64 not given
+   * @param {string} [opts.signatureBase64] - if you prefer to sign externally
+   */
+  authenticate({
+    publicKeyBase64Der,
+    nonce,
+    wantNewId = true,
+    privateKey,
+    signatureBase64
+  }) {
+    const signature = ensureSignature({ signatureBase64, privateKey, nonce });
+    const params = {
+      publicKey: publicKeyBase64Der,
+      signature,
+      nonce,
+      wantNewId
+    };
+    return new JsonRpcBuilder(methodNames.authenticate, params);
+  },
+
+  /**
+   * registerCapabilities
+   * @param {object} opts
+   * @param {string} opts.displayName
+   * @param {('volatile'|'persistent')} [opts.mailboxMode='persistent']
+   * @param {Array<object>} [opts.tools=[]] - [{ name, description, inputSchema, outputSchema?, scopes? }]
+   * @param {string|string[]} [opts.scopes=['global']]
+   * @param {string} [opts.parentAgentId]
+   */
+  registerCapabilities({
+    displayName,
+    mailboxMode = 'persistent',
+    tools = [],
+    scopes = ['global'],
+    parentAgentId
+  } = {}) {
+    if (!displayName) throw new Error('displayName is required');
+    /** @type {any} */
+    const params = { displayName, mailboxMode, tools, scopes };
+    if (parentAgentId !== undefined) params.parentAgentId = parentAgentId;
+    return new JsonRpcBuilder(methodNames.registerCapabilities, params);
+  },
+
+  /** ping (notification) */
+  ping() {
+    return new JsonRpcBuilder(
+      methodNames.ping,
+      undefined,
+      /* notification */ true
+    );
+  },
+
+  /**
+   * listTools
+   * @param {object} [opts]
+   * @param {string|string[]} [opts.scopes=['global']]
+   */
+  listTools({ scopes = ['global'] } = {}) {
+    return new JsonRpcBuilder(methodNames.listTools, { scopes });
+  },
+
+  /**
+   * callAbility
+   * @param {object} opts
+   * @param {string} opts.toolName
+   * @param {object} [opts.args]
+   * @param {string} [opts.requestId] - correlation ID; generated if omitted
+   */
+  callAbility({ toolName, args = {}, requestId = undefined }) {
+    if (!toolName) throw new Error('toolName is required');
+    const rid = requestId ?? newRequestId();
+    return new JsonRpcBuilder(methodNames.callAbility, {
+      toolName,
+      args,
+      requestId: rid
+    });
+  },
+
+  /**
+   * abilityResult (notification)
+   * @param {object} opts
+   * @param {string} opts.requestId
+   * @param {string} opts.toSessionId
+   * @param {any} [opts.result]
+   * @param {string|null} [opts.error]
+   */
+  abilityResult({ requestId, toSessionId, result = undefined, error = null }) {
+    if (!requestId) throw new Error('requestId is required');
+    if (!toSessionId) throw new Error('toSessionId is required');
+    const params = { requestId, toSessionId };
+    if (result !== undefined) params.result = result;
+    if (error !== null) params.error = error;
+    return new JsonRpcBuilder(
+      methodNames.abilityResult,
+      params,
+      /* notification */ true
+    );
+  },
+
+  /**
+   * Build an agent ability definition object.
+   * Kept shape compatible with current broker "tools" array.
+   * @param {object} opts
+   * @param {string} opts.name
+   * @param {string} opts.description
+   * @param {object} opts.inputSchema
+   * @param {object} [opts.outputSchema]
+   * @param {string[]} [opts.scopes]
+   */
+  agentAbility({ name, description, inputSchema, outputSchema, scopes }) {
+    if (!name) throw new Error('ability.name is required');
+    if (!description) throw new Error('ability.description is required');
+    if (!inputSchema) throw new Error('ability.inputSchema is required');
+    /** @type {any} */
+    const def = { name, description, inputSchema };
+    if (outputSchema) def.outputSchema = outputSchema;
+    if (scopes) def.scopes = scopes;
+    return def;
+  },
+
+  /** Short alias. */
+  ability(opts) {
+    return this.agentAbility(opts);
+  }
+};
+
+/** Namespace: MCP bridge message builders (subset as per README). */
+export const MCP = {
+  initialize({
+    protocolVersion = '2025-06-18',
+    capabilities = {},
+    clientInfo = { name: 'mcp-client', version: '1.0.0' }
+  } = {}) {
+    const params = {
+      protocolVersion,
+      capabilities: {
+        resources: { subscribe: false, ...capabilities.resources },
+        tools: true,
+        prompts: { subscribe: false, ...capabilities.prompts },
+        sampling: false,
+        ...capabilities
+      },
+      clientInfo
+    };
+    return new JsonRpcBuilder('initialize', params);
+  },
+  initialized() {
+    return new JsonRpcBuilder('initialized', undefined, true);
+  },
+  toolsList() {
+    return new JsonRpcBuilder('tools/list', {});
+  },
+  toolsCall({ name, arguments: args = {} }) {
+    if (!name) throw new Error('name is required');
+    return new JsonRpcBuilder('tools/call', { name, arguments: args });
+  }
+};
+
+/** Helpers for common agent handshake flows */
+export const Flows = {
+  /**
+   * Build all handshake messages for an agent given the broker's hello result and your keys.
+   * @param {object} opts
+   * @param {KeyObject} opts.publicKey
+   * @param {KeyObject} opts.privateKey
+   * @param {string} opts.nonce - From hello result
+   * @param {string} opts.displayName
+   * @param {Array<object>} opts.tools
+   * @param {('volatile'|'persistent')} [opts.mailboxMode]
+   * @param {string|string[]} [opts.scopes=['global']]
+   */
+  completeAgentHandshake({
+    publicKey,
+    privateKey,
+    nonce,
+    displayName,
+    tools,
+    mailboxMode = 'volatile',
+    scopes = ['global']
+  }) {
+    const ids = new IdFactory(); // fresh id sequence for this flow
+    const hello = Broker.hello({ role: 'agent' }).id(ids.next()).build();
+    const auth = Broker.authenticate({
+      publicKeyBase64Der: toBase64Der(publicKey),
+      privateKey,
+      nonce,
+      wantNewId: true
+    })
+      .id(ids.next())
+      .build();
+    const reg = Broker.registerCapabilities({
+      displayName,
+      tools,
+      mailboxMode,
+      scopes
+    })
+      .id(ids.next())
+      .build();
+    return { hello, authenticate: auth, register: reg };
+  }
+};
+
+const BrokerMessageBuilder = {
+  JsonRpcBuilder,
+  IdFactory,
+  newRequestId,
+  toBase64Der,
+  Broker,
+  MCP,
+  Flows,
+  configureMethods,
+  _methodNames: methodNames // exposed for debugging
+};
+
+export default BrokerMessageBuilder;