feat(kernel-agents): author built-in capabilities as pattern-guarded exos

Rewrite the `math`, `end`, and `examples` capabilities as discoverable exos
built with the `described*()` combinators, so each capability's argument shape
is enforced by the exo's interface guard at invocation rather than only
advertised in the prompt. A mistyped argument now fails with a guard rejection
at the membrane instead of surfacing deep inside the capability.

Each module derives its `{ func, schema }` capability specs from the exo via a
new synchronous `discoverLocal`, so all existing consumers (example transcripts,
e2e tests, the REPL evaluator, prepare-attempt) keep the same spec shape and
`makeEnd` stays synchronous. `end`'s closed-over result object is intentionally
left un-hardened so the exo method can mutate it.

`getMoonPhase` loses its (already unsupported, `@ts-expect-error`'d) `enum`
return hint; `end`'s off-spec per-argument `required` flags are gone, with
`final` required and `attachments` optional expressed by the guard.

Install the endoify mock as a package-wide vitest setup so capability modules,
which now build exos at import, have a `harden` global before they load.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: grypez

packages/kernel-agents/CHANGELOG.md

@@ -7,4 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `discoverLocal`, a synchronous variant of `discover` for converting a local, in-realm discoverable exo into a capability record without an `await`
+
+### Changed
+
+- The built-in capabilities (`math`, `end`, `examples`) are now pattern-guarded discoverable exos authored with the `described*()` combinators, so their argument shapes are enforced by the exo's interface guard at invocation rather than only described in the prompt
+
 [Unreleased]: https://github.com/MetaMask/ocap-kernel/

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

@@ -5,8 +5,50 @@ 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.
+ * Invoke a discoverable exo's method with positional arguments. The async
+ * variant ({@link discover}) sends over an eventual-send boundary; the local
+ * variant ({@link discoverLocal}) calls the in-realm exo directly. Either way
+ * the exo's interface guard enforces the argument shape.
+ */
+type Invoke = (method: string, positionalArgs: unknown[]) => unknown;
+
+/**
+ * Build a {@link CapabilityRecord} from a method-schema description, mapping each
+ * capability's object arguments to positional arguments for the exo method.
+ *
+ * IMPORTANT: this relies on each `schema.args` having keys in the same order as
+ * the method's parameters. Schemas authored with the `described*()` combinators
+ * (`@metamask/kernel-utils`) satisfy this by construction, since their `args`
+ * record is built in declared positional order.
+ *
+ * @param description - The exo's method schemas, keyed by method name.
+ * @param invoke - How to invoke a method with positional arguments.
+ * @returns The capability record.
+ */
+const capabilitiesFrom = (
+  description: Record<string, MethodSchema>,
+  invoke: Invoke,
+): CapabilityRecord =>
+  Object.fromEntries(
+    Object.entries(description).map(([name, schema]) => {
+      const argNames = Object.keys(schema.args);
+      // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+      const func = async (args: Record<string, unknown>) =>
+        invoke(
+          name,
+          argNames.map((argName) => args[argName]),
+        );
+      return [name, { func, schema }] as [
+        string,
+        CapabilitySpec<never, unknown>,
+      ];
+    }),
+  );
+
+/**
+ * Discover the capabilities of a (possibly remote) discoverable exo. Fetches the
+ * schema over an eventual-send boundary and creates capabilities that invoke the
+ * exo's methods the same way.
  *
  * @param exo - The discoverable exo to convert to a capability record.
  * @returns A promise for a capability record.
@@ -19,35 +61,29 @@ export const discover = async (
     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 capabilitiesFrom(description, async (method, positionalArgs) =>
+    // @ts-expect-error - E type doesn't remember method names
+    E(exo)[method](...positionalArgs),
   );
+};
 
-  return capabilities;
+/**
+ * Discover the capabilities of a local, in-realm discoverable exo synchronously.
+ * Used by capability modules that build their own exo at load time and want to
+ * expose it as a capability record without an `await`. The exo still enforces
+ * its interface guard on every (direct) call.
+ *
+ * @param exo - The local discoverable exo to convert to a capability record.
+ * @returns A capability record.
+ */
+export const discoverLocal = <Exo extends object>(
+  exo: Exo,
+): CapabilityRecord => {
+  const methods = exo as unknown as {
+    [GET_DESCRIPTION]: () => Record<string, MethodSchema>;
+  } & Record<string, ((...args: unknown[]) => unknown) | undefined>;
+  const description = methods[GET_DESCRIPTION]();
+  return capabilitiesFrom(description, (method, positionalArgs) =>
+    methods[method]?.(...positionalArgs),
+  );
 };

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

@@ -1,5 +1,8 @@
+import { S, makeDiscoverableExo } from '@metamask/kernel-utils';
+
+import { discoverLocal } from './discover.ts';
+import type { CapabilitySpec } from '../types.ts';
 import { ifDefined } from '../utils.ts';
-import { capability } from './capability.ts';
 
 /**
  * A factory function to make a task's `end` capability, which stores the first
@@ -10,36 +13,49 @@ import { capability } from './capability.ts';
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export const makeEnd = <Result>() => {
+  // Captured, mutable state for the first final result. Intentionally NOT
+  // hardened: the exo method below closes over and mutates it.
   const result: { final?: Result; attachments?: Record<string, unknown> } = {};
-  const end = capability(
-    async ({
-      final,
-      attachments,
-    }: {
-      final: Result;
-      attachments?: Record<string, unknown>;
-    }): Promise<void> => {
-      if (!Object.hasOwn(result, 'final')) {
-        Object.assign(result, { final, ...ifDefined({ attachments }) });
-      }
-    },
-    {
-      description: 'Return a final response to the user.',
-      args: {
-        final: {
-          required: true,
-          type: 'string',
-          description:
+
+  const { interfaceGuard, schemas } = S.interface('End', {
+    end: S.method(
+      'Return a final response to the user.',
+      [
+        S.arg(
+          'final',
+          S.string(
             'A concise final response that restates the requested information.',
-        },
-        attachments: {
-          required: false,
-          type: 'object',
-          description: 'Attachments to the final response.',
-        },
+          ),
+        ),
+        S.arg('attachments', S.record('Attachments to the final response.'), {
+          optional: true,
+        }),
+      ],
+      S.nothing(),
+    ),
+  });
+
+  const exo = makeDiscoverableExo(
+    'End',
+    {
+      async end(
+        final: Result,
+        attachments?: Record<string, unknown>,
+      ): Promise<void> {
+        if (!Object.hasOwn(result, 'final')) {
+          Object.assign(result, { final, ...ifDefined({ attachments }) });
+        }
       },
     },
+    schemas,
+    interfaceGuard,
   );
+
+  const { end } = discoverLocal(exo) as Record<
+    'end',
+    CapabilitySpec<never, unknown>
+  >;
+
   return [end, () => 'final' in result, () => result.final as Result] as const;
 };
 

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

@@ -1,43 +1,13 @@
-import { capability } from './capability.ts';
+import { S, makeDiscoverableExo } from '@metamask/kernel-utils';
+
+import { discoverLocal } from './discover.ts';
+import type { CapabilitySpec } from '../types.ts';
 
 type SearchResult = {
   source: string;
   published: string;
   snippet: string;
 };
-export const search = capability(
-  async ({ query }: { query: string }): Promise<SearchResult[]> => [
-    {
-      source: 'https://www.google.com',
-      published: '2025-01-01',
-      snippet: `No information found for ${query}`,
-    },
-  ],
-  {
-    description: 'Search the web for information.',
-    args: { query: { type: 'string', description: 'The query to search for' } },
-    returns: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          source: {
-            type: 'string',
-            description: 'The source of the information.',
-          },
-          published: {
-            type: 'string',
-            description: 'The date the information was published.',
-          },
-          snippet: {
-            type: 'string',
-            description: 'The snippet of information.',
-          },
-        },
-      },
-    },
-  },
-);
 
 const moonPhases = [
   'new moon',
@@ -51,20 +21,53 @@ const moonPhases = [
 ] as const;
 type MoonPhase = (typeof moonPhases)[number];
 
-export const getMoonPhase = capability(
-  async (): Promise<MoonPhase> =>
-    moonPhases[Math.floor(Math.random() * moonPhases.length)] as MoonPhase,
+const { interfaceGuard, schemas } = S.interface('Examples', {
+  search: S.method(
+    'Search the web for information.',
+    [S.arg('query', S.string('The query to search for'))],
+    S.arrayOf(
+      S.object({
+        source: S.string('The source of the information.'),
+        published: S.string('The date the information was published.'),
+        snippet: S.string('The snippet of information.'),
+      }),
+    ),
+  ),
+  // TODO: Add enum support to the capability schema so the moon phases can be
+  // advertised as the allowed return values.
+  getMoonPhase: S.method(
+    'Get the current phase of the moon.',
+    [],
+    S.string('The current phase of the moon.'),
+  ),
+});
+
+const examplesExo = makeDiscoverableExo(
+  'Examples',
   {
-    description: 'Get the current phase of the moon.',
-    args: {},
-    returns: {
-      type: 'string',
-      // TODO: Add enum support to the capability schema
-      // @ts-expect-error - enum is not supported by the capability schema
-      enum: moonPhases,
-      description: 'The current phase of the moon.',
+    async search(query: string): Promise<SearchResult[]> {
+      return [
+        {
+          source: 'https://www.google.com',
+          published: '2025-01-01',
+          snippet: `No information found for ${query}`,
+        },
+      ];
+    },
+    async getMoonPhase(): Promise<MoonPhase> {
+      return moonPhases[
+        Math.floor(Math.random() * moonPhases.length)
+      ] as MoonPhase;
     },
   },
+  schemas,
+  interfaceGuard,
 );
 
-export const exampleCapabilities = { search, getMoonPhase };
+const capabilities = discoverLocal(examplesExo) as Record<
+  'search' | 'getMoonPhase',
+  CapabilitySpec<never, unknown>
+>;
+
+export const { search, getMoonPhase } = capabilities;
+export const exampleCapabilities = capabilities;