feat: Add makeDiscoverableExo constructor (#705)

Closes: #649 

This PR adds the `makeDiscoverableExo` constructor, which associates to
a capability interface the sort of descriptive metadata needed by
`@ocap/kernel-agents` to perform agentic capability composition.

Author: grypez

packages/kernel-agents/package.json

@@ -102,6 +102,7 @@
     "node": "^20.11 || >=22"
   },
   "dependencies": {
+    "@endo/eventual-send": "^1.3.4",
     "@metamask/kernel-errors": "workspace:^",
     "@metamask/kernel-utils": "workspace:^",
     "@metamask/logger": "workspace:^",

packages/kernel-agents/src/capabilities/discover.ts

@@ -0,0 +1,49 @@
+import { E } from '@endo/eventual-send';
+import type { DiscoverableExo, MethodSchema } from '@metamask/kernel-utils';
+
+import type { CapabilityRecord, CapabilitySpec } from '../types.ts';
+
+/**
+ * Discover the capabilities of a discoverable exo. Intended for use from inside a vat.
+ * This function fetches the schema from the discoverable exo and creates capabilities that can be used by kernel agents.
+ *
+ * @param exo - The discoverable exo to convert to a capability record.
+ * @returns A promise for a capability record.
+ */
+export const discover = async (
+  exo: DiscoverableExo,
+): Promise<CapabilityRecord> => {
+  // @ts-expect-error - E type doesn't remember method names
+  const description = (await E(exo).describe()) as Record<string, MethodSchema>;
+
+  const capabilities: CapabilityRecord = Object.fromEntries(
+    Object.entries(description).map(([name, schema]) => {
+      // Get argument names in order from the schema.
+      // IMPORTANT: This relies on the schema's args object having keys in the same
+      // order as the method's parameters. The schema must be defined with argument
+      // names matching the method parameter order (e.g., for method `add(a, b)`,
+      // the schema must have `args: { a: ..., b: ... }` in that order).
+      // JavaScript objects preserve insertion order for string keys, so Object.keys()
+      // will return keys in the order they were defined in the schema.
+      const argNames = Object.keys(schema.args);
+
+      // Create a capability function that accepts an args object
+      // and maps it to positional arguments for the exo method
+      // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+      const func = async (args: Record<string, unknown>) => {
+        // Map object arguments to positional arguments in schema order.
+        // The order of argNames matches the method parameter order by convention.
+        const positionalArgs = argNames.map((argName) => args[argName]);
+        // @ts-expect-error - E type doesn't remember method names
+        return E(exo)[name](...positionalArgs);
+      };
+
+      return [name, { func, schema }] as [
+        string,
+        CapabilitySpec<never, unknown>,
+      ];
+    }),
+  );
+
+  return capabilities;
+};

packages/kernel-agents/src/capabilities/examples.ts

@@ -18,7 +18,7 @@ export const search = capability(
     args: { query: { type: 'string', description: 'The query to search for' } },
     returns: {
       type: 'array',
-      item: {
+      items: {
         type: 'object',
         properties: {
           source: {

packages/kernel-agents/src/capabilities/math.ts

@@ -19,7 +19,7 @@ export const add = capability(
     summands.reduce((acc, summand) => acc + summand, 0),
   {
     description: 'Add a list of numbers.',
-    args: { summands: { type: 'array', item: { type: 'number' } } },
+    args: { summands: { type: 'array', items: { type: 'number' } } },
     returns: { type: 'number', description: 'The sum of the numbers.' },
   },
 );
@@ -33,7 +33,7 @@ export const multiply = capability(
       factors: {
         type: 'array',
         description: 'The list of numbers to multiply.',
-        item: { type: 'number' },
+        items: { type: 'number' },
       },
     },
     returns: { type: 'number', description: 'The product of the factors.' },

packages/kernel-agents/src/index.test.ts

@@ -6,7 +6,7 @@ import * as indexModule from './index.ts';
 describe('index', () => {
   it('has the expected exports', () => {
     expect(Object.keys(indexModule).sort()).toStrictEqual(
-      expect.arrayContaining([]),
+      expect.arrayContaining(['discover']),
     );
   });
 });

packages/kernel-agents/src/index.ts

@@ -1 +1,2 @@
 export type { CapabilityRecord } from './types.ts';
+export { discover } from './capabilities/discover.ts';

packages/kernel-agents/src/types/capability.ts

@@ -1,4 +1,4 @@
-import type { JsonSchema } from './json-schema.ts';
+import type { JsonSchema } from '@metamask/kernel-utils';
 
 export type Capability<Args extends Record<string, unknown>, Return = null> = (
   args: Args,

packages/kernel-agents/src/types/json-schema.ts

@@ -9,6 +9,7 @@
     { "path": "../kernel-language-model-service" },
     { "path": "../kernel-utils" },
     { "path": "../logger" },
+    { "path": "../ocap-kernel" },
     { "path": "../repo-tools" }
   ],
   "include": [

packages/kernel-agents/tsconfig.json

@@ -0,0 +1,79 @@
+import { makeDiscoverableExo } from '@metamask/kernel-utils/discoverable';
+import { makeDefaultExo } from '@metamask/kernel-utils/exo';
+
+/**
+ * Build function for a vat that exports a discoverable exo capability.
+ *
+ * @param {*} _vatPowers - Special powers granted to this vat (not used here).
+ * @param {*} _parameters - Initialization parameters from the vat's config object.
+ * @param {*} _baggage - Root of vat's persistent state (not used here).
+ * @returns {*} The root object for the new vat.
+ */
+export function buildRootObject(_vatPowers, _parameters, _baggage) {
+  const calculator = makeDiscoverableExo(
+    'Calculator',
+    {
+      add: (a, b) => a + b,
+      multiply: (a, b) => a * b,
+      greet: (name) => `Hello, ${name}!`,
+    },
+    {
+      add: {
+        description: 'Adds two numbers together',
+        args: {
+          a: {
+            type: 'number',
+            description: 'First number',
+          },
+          b: {
+            type: 'number',
+            description: 'Second number',
+          },
+        },
+        returns: {
+          type: 'number',
+          description: 'The sum of the two numbers',
+        },
+      },
+      multiply: {
+        description: 'Multiplies two numbers together',
+        args: {
+          a: {
+            type: 'number',
+            description: 'First number',
+          },
+          b: {
+            type: 'number',
+            description: 'Second number',
+          },
+        },
+        returns: {
+          type: 'number',
+          description: 'The product of the two numbers',
+        },
+      },
+      greet: {
+        description: 'Greets a person by name',
+        args: {
+          name: {
+            type: 'string',
+            description: 'The name of the person to greet',
+          },
+        },
+        returns: {
+          type: 'string',
+          description: 'A greeting message',
+        },
+      },
+    },
+  );
+
+  return makeDefaultExo('root', {
+    bootstrap() {
+      return 'discoverable-capability-vat ready';
+    },
+    getCalculator() {
+      return calculator;
+    },
+  });
+}