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

## Explanation

Rewrites the `math`, `end`, and `examples` capabilities as discoverable
exos
built with the `described*()` combinators (added in #958, now on
`main`), 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 via a new
synchronous `makeInternalCapabilities` constructor, which builds the
pattern-guarded exo (kept private as the in-realm enforcement membrane)
and
projects a capability record from the just-authored schemas — without
round-tripping through `GET_DESCRIPTION`. All existing consumers
(example
transcripts, 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.

`makeInternalCapabilities` asserts at construction that the
implementation and
schema method sets match exactly. A missing implementation already
throws inside
`makeDiscoverableExo`, but an extra implementation absent from the
schema would
otherwise be silently accepted by the guard's `defaultGuards:
'passable'` and
never be reachable as a capability — so an authoring typo (e.g. `serch`
vs
`search`) now fails loudly at construction instead of surfacing as a
capability
that resolves to `undefined`. A colocated `discover.test.ts` covers the
positional-arg mapping, guard rejection at the membrane, and this
construction
check.

Installs the endoify mock as a package-wide vitest setup, since
capability
modules now build exos at import and need a `harden` global before they
load.

### Notable behavior changes

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

## Test plan

- [x] `yarn workspace @ocap/kernel-agents test` (58 pass) and
`test:dev:quiet`
- [x] `yarn workspace @ocap/kernel-agents-repl test` (178 pass)
- [x] `build` + `lint` for both packages; changelog validates
- [ ] Local-only `kernel-test-local` agent e2e: see #961 (out of scope
here)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches core agent capability invocation and changes runtime
validation behavior (guard rejections vs deep errors), though external
capability shapes and `makeEnd` sync API stay the same.
> 
> **Overview**
> Built-in **`math`**, **`end`**, and **`examples`** capabilities are no
longer hand-authored with `capability()`; they are built via new
**`makeInternalCapabilities`**, which wraps implementations in a private
pattern-guarded discoverable exo and projects the same `{ func, schema
}` shape agents already use. Invalid or missing arguments are rejected
at the exo interface guard before implementation code runs.
> 
> **`discover`** is refactored to share **`capabilitiesFrom`** with the
local path so remote and in-realm invocation both map named-arg objects
to positional exo calls the same way. **`makeInternalCapabilities`**
also fails at construction if schema and implementation method names do
not match exactly.
> 
> Tests cover mapping, membrane rejection, and the construction check;
package **vitest** loads the endoify mock globally because capability
modules build exos at import. **`getMoonPhase`** no longer advertises an
unsupported `enum` return hint; **`end`** optional/required args are
expressed only via the guard schema.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
06d6853. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: grypez

packages/kernel-agents/CHANGELOG.md

@@ -7,4 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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 ([#959](https://github.com/MetaMask/ocap-kernel/pull/959))
+
 [Unreleased]: https://github.com/MetaMask/ocap-kernel/

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

@@ -0,0 +1,88 @@
+import { S } from '@metamask/kernel-utils';
+import { describe, expect, it } from 'vitest';
+
+import { makeInternalCapabilities } from './discover.ts';
+
+/**
+ * Whether a promise rejects. Used instead of `.rejects.toThrow()` because the
+ * interface guard rejects with an opaque (non-`Error`) value under the test
+ * shim; here we only care that the membrane blocked the call.
+ *
+ * @param promise - The promise to observe.
+ * @returns `true` if the promise rejects, `false` if it resolves.
+ */
+const rejects = async (promise: Promise<unknown>): Promise<boolean> => {
+  try {
+    await promise;
+    return false;
+  } catch {
+    return true;
+  }
+};
+
+// Build the capabilities once, mirroring how the built-in capability modules
+// construct their exo at import.
+const capabilities = makeInternalCapabilities(
+  'Test',
+  {
+    async count(word: string) {
+      return word.length;
+    },
+    async add(summands: number[]) {
+      return summands.reduce((acc, summand) => acc + summand, 0);
+    },
+  },
+  S.interface('Test', {
+    count: S.method(
+      'Count characters.',
+      [S.arg('word', S.string('The string to measure.'))],
+      S.number('The number of characters.'),
+    ),
+    add: S.method(
+      'Add numbers.',
+      [S.arg('summands', S.arrayOf(S.number()))],
+      S.number('The sum.'),
+    ),
+  }),
+);
+
+describe('makeInternalCapabilities', () => {
+  it('projects a capability record keyed by the schema method names', () => {
+    expect(Object.keys(capabilities)).toStrictEqual(['count', 'add']);
+    expect(capabilities.count.schema.description).toBe('Count characters.');
+  });
+
+  it('maps the named-args object to positional args and invokes the method', async () => {
+    expect(await capabilities.count.func({ word: 'abcdefg' })).toBe(7);
+    expect(await capabilities.add.func({ summands: [1, 2, 3, 4] })).toBe(10);
+  });
+
+  it('rejects a mistyped argument at the exo membrane', async () => {
+    // `count` expects a string; the interface guard rejects a number before the
+    // implementation runs.
+    expect(
+      await rejects(capabilities.count.func({ word: 12345 } as never)),
+    ).toBe(true);
+  });
+
+  it('rejects a missing required argument at the exo membrane', async () => {
+    expect(await rejects(capabilities.add.func({} as never))).toBe(true);
+  });
+
+  it('throws at construction when an implementation has no matching schema', () => {
+    expect(() =>
+      makeInternalCapabilities(
+        'Skewed',
+        {
+          // Typo: the schema declares `search`, not `serch`.
+          async serch(query: string) {
+            return query;
+          },
+        },
+        S.interface('Skewed', {
+          search: S.method('Search.', [S.arg('query', S.string())], S.string()),
+        }),
+      ),
+    ).toThrow(/implementation and schema method names must match/u);
+  });
+});

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

@@ -1,12 +1,58 @@
 import { E } from '@endo/eventual-send';
-import { GET_DESCRIPTION } from '@metamask/kernel-utils';
-import type { DiscoverableExo, MethodSchema } from '@metamask/kernel-utils';
+import { GET_DESCRIPTION, makeDiscoverableExo } from '@metamask/kernel-utils';
+import type {
+  DescribedInterface,
+  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 makeInternalCapabilities}) 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 +65,68 @@ 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;
+/**
+ * Construct an in-realm capability record from a guard+schema description and
+ * the method implementations, building (and then keeping private) the
+ * pattern-guarded exo that enforces the argument shape on every call.
+ *
+ * Unlike {@link discover}, this never crosses an eventual-send boundary and
+ * never reads `GET_DESCRIPTION`: the schemas are the ones just authored with the
+ * `described*()` combinators (`@metamask/kernel-utils`), so there is no
+ * round-trip through the exo to recover what the caller already holds. The exo
+ * is used purely as the in-realm enforcement membrane and is not surfaced —
+ * internal capabilities are guarded closures, not passable exos. To expose a
+ * capability across a boundary, publish a {@link DiscoverableExo} and
+ * {@link discover} it instead.
+ *
+ * @param name - The exo/interface name.
+ * @param methods - The method implementations, keyed by method name.
+ * @param described - The interface guard and per-method schemas, e.g. from
+ * `S.interface(...)`.
+ * @returns A capability record keyed by the method names.
+ */
+export const makeInternalCapabilities = <Method extends string>(
+  name: string,
+  methods: Record<Method, (...args: never[]) => Promise<unknown>>,
+  described: DescribedInterface,
+): CapabilityRecord<Method> => {
+  const { interfaceGuard, schemas } = described;
+  // The implementation and schema method sets must match exactly. A missing
+  // implementation already throws inside `makeDiscoverableExo`, but an extra
+  // implementation absent from the schema is silently accepted by the guard's
+  // `defaultGuards: 'passable'` and would never be reachable as a capability.
+  // Catch both here so an authoring typo (e.g. `serch` vs `search`) fails loudly
+  // at construction instead of surfacing as a capability that resolves to
+  // `undefined`.
+  const missing = Object.keys(schemas).filter((method) => !(method in methods));
+  const extra = Object.keys(methods).filter((method) => !(method in schemas));
+  if (missing.length > 0 || extra.length > 0) {
+    throw new Error(
+      `makeInternalCapabilities("${name}"): implementation and schema method names must match. ` +
+        `Schema methods without an implementation: [${missing.join(', ')}]; ` +
+        `implementations without a schema: [${extra.join(', ')}].`,
+    );
+  }
+  const exo = makeDiscoverableExo(
+    name,
+    methods as Record<string, (...args: unknown[]) => unknown>,
+    schemas,
+    interfaceGuard,
+  );
+  const dispatch = exo as unknown as Record<
+    string,
+    (...args: unknown[]) => unknown
+  >;
+  // Dispatch as a member call so the exo method keeps its `this` binding. The
+  // construction check above guarantees `method` is present, so the optional
+  // chain never short-circuits in practice.
+  return capabilitiesFrom(schemas, (method, positionalArgs) =>
+    dispatch[method]?.(...positionalArgs),
+  ) as CapabilityRecord<Method>;
 };

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

@@ -1,5 +1,7 @@
+import { S } from '@metamask/kernel-utils';
+
+import { makeInternalCapabilities } from './discover.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 +12,41 @@ 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 }) });
-      }
-    },
+
+  const { end } = makeInternalCapabilities(
+    'End',
     {
-      description: 'Return a final response to the user.',
-      args: {
-        final: {
-          required: true,
-          type: 'string',
-          description:
-            'A concise final response that restates the requested information.',
-        },
-        attachments: {
-          required: false,
-          type: 'object',
-          description: 'Attachments to the final response.',
-        },
+      async end(
+        final: Result,
+        attachments?: Record<string, unknown>,
+      ): Promise<void> {
+        if (!Object.hasOwn(result, 'final')) {
+          Object.assign(result, { final, ...ifDefined({ attachments }) });
+        }
       },
     },
+    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.',
+            ),
+          ),
+          S.arg('attachments', S.record('Attachments to the final response.'), {
+            optional: true,
+          }),
+        ],
+        S.nothing(),
+      ),
+    }),
   );
+
   return [end, () => 'final' in result, () => result.final as Result] as const;
 };