From ba04c18741c38ac05028cfaa38040eb731d31108 Mon Sep 17 00:00:00 2001
From: Ubuntu <ubuntu@ip-172-31-1-241.ec2.internal>
Date: Mon, 8 Jun 2026 18:46:44 +0000
Subject: [PATCH] docs: clarify actor accept schemas

---
 README.md                                    | 11 +++++++----
 demos/fresh-server-actor/src/server.ts       |  2 +-
 demos/fresh-web-page/src/main.ts             |  2 +-
 demos/fresh-web-page/vite.config.ts          |  2 +-
 demos/standalone-greeter/src/GreeterActor.ts |  2 +-
 packages/sdk/README.md                       |  2 +-
 6 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 1425288..0f5692e 100644
--- a/README.md
+++ b/README.md
@@ -104,7 +104,9 @@ cat > GreeterActor.mjs <<'EOF'
 import { MatrixActor } from '@open-matrix/sdk';
 
 export default class GreeterActor extends MatrixActor {
-  static accepts = { echo: {} };
+  static accepts = {
+    echo: { description: 'Echo a message', message: 'string' },
+  };
   onEcho(payload = {}) {
     return {
       ok: true,
@@ -130,8 +132,9 @@ Expected result: the actor run command prints JSON with `ok: true` and the
 `echo` result from `GreeterActor`.
 
 Handler names are part of the Matrix actor contract: `static accepts = { echo:
-{} }` maps to `onEcho(payload)`. Do not implement `echo(payload)` directly; the
-CLI rejects that shape before it connects to the broker.
+... }` maps to `onEcho(payload)`. Do not implement `echo(payload)` directly; the
+CLI rejects that shape before it connects to the broker. Include parameter
+fields such as `message: 'string'` so agents can construct valid payloads.
 
 If you need the HiveCast browser proof and `pnpm doctor:hivecast` reports
 missing Chromium:
@@ -170,7 +173,7 @@ import {
 
 class EchoActor extends MatrixActor {
   static accepts = {
-    echo: {},
+    echo: { description: 'Echo a message', message: 'string' },
   };
 
   onEcho(payload: { message?: string }) {
diff --git a/demos/fresh-server-actor/src/server.ts b/demos/fresh-server-actor/src/server.ts
index 8ce3f87..085c5b1 100644
--- a/demos/fresh-server-actor/src/server.ts
+++ b/demos/fresh-server-actor/src/server.ts
@@ -9,7 +9,7 @@ import {
 
 class FreshServerEchoActor extends MatrixActor {
   static accepts = {
-    echo: {},
+    echo: { description: 'Echo a message', message: 'string' },
     getStatus: {},
   };
 
diff --git a/demos/fresh-web-page/src/main.ts b/demos/fresh-web-page/src/main.ts
index f03a80d..84ba764 100644
--- a/demos/fresh-web-page/src/main.ts
+++ b/demos/fresh-web-page/src/main.ts
@@ -8,7 +8,7 @@ import type { HiveCastActorCredential } from '@open-matrix/sdk';
 
 class FreshBrowserEchoActor extends MatrixActor {
   static accepts = {
-    echo: {},
+    echo: { description: 'Echo a message', message: 'string' },
     getStatus: {},
   };
 
diff --git a/demos/fresh-web-page/vite.config.ts b/demos/fresh-web-page/vite.config.ts
index 2e1af26..e4823c4 100644
--- a/demos/fresh-web-page/vite.config.ts
+++ b/demos/fresh-web-page/vite.config.ts
@@ -38,7 +38,7 @@ function hiveCastActorCredentialPlugin(): Plugin {
             actorId: 'FreshBrowserEchoActor',
             packageId: 'matrix-sdk-demo-fresh-web-page',
             runtimeId: `fresh-web-${process.pid}`,
-            accepts: { echo: {}, getStatus: {} },
+            accepts: { echo: { description: 'Echo a message', message: 'string' }, getStatus: {} },
             ttlSeconds: 300,
           });
           sendJson(res, 200, credential);
diff --git a/demos/standalone-greeter/src/GreeterActor.ts b/demos/standalone-greeter/src/GreeterActor.ts
index 1f777a7..703a6d2 100644
--- a/demos/standalone-greeter/src/GreeterActor.ts
+++ b/demos/standalone-greeter/src/GreeterActor.ts
@@ -2,7 +2,7 @@ import { MatrixActor } from '@open-matrix/core';
 
 export class GreeterActor extends MatrixActor {
   static accepts = {
-    echo: {},
+    echo: { description: 'Echo a message', message: 'string' },
     getStatus: {},
   };
 
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 871a378..1ba663e 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -29,7 +29,7 @@ const credential = await exchangeHiveCastActorCredential({
   apiKey: process.env.MATRIX_API_KEY!,
 }, {
   mount: 'fresh.server.echo',
-  accepts: { echo: {} },
+  accepts: { echo: { description: 'Echo a message', message: 'string' } },
 });
 ```