@localhostdevs/sdk 0.14.0 → 0.16.0

package/README.md

@@ -22,11 +22,11 @@ const bot = new Bot({
   // apiKey: process.env.BOT_SECRET,  // optional; auto-read from env if unset
 });
 
-bot.cmd('ping', async (ctx) => {
+bot.cmd({ name: 'ping' }, async (ctx) => {
   await ctx.reply({ text: 'pong' });
 });
 
-bot.cmd('echo', async (ctx) => {
+bot.cmd({ name: 'echo' }, async (ctx) => {
   await ctx.reply({ text: `echo: ${JSON.stringify(ctx.args)}` });
 });
 
@@ -53,15 +53,63 @@ The bot stays online for as long as the process runs. The gateway keeps the conn
 | `serverUrl`          | `string`            | `wss://bot-api.localhostdevs.com/bot` (override with `LHD_SERVER_URL`)  | Production gateway is baked in — most users leave this alone. Only override for local dev or self-hosted gateways.                  |
 | `idempotencyLruSize` | `number`            | `1024`                                                            | How many recent message IDs to remember for deduplication.                                        |
 
-### `bot.cmd(name, handler)`
+### `bot.cmd(def, handler)`
 
-Register a handler for a command. Must be called before `connect()`. Handler receives a `CommandContext`:
+Register a handler for a command. Must be called before `connect()`. The first argument is a **command definition object** with the following fields:
+
+| Field         | Type                                       | Notes                                                                                                                                           |
+| ------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | `string` (required)                        | Command name consumers dispatch (e.g. `'ping'`, `'topic'`).                                                                                     |
+| `description` | `string`                                   | Human-readable description shown on the marketplace/workflow picker.                                                                             |
+| `args`        | `Record<string, ArgSpec>`                  | Declare the expected arguments (see below). **Advertise-only** by default — fills the marketplace and workflow picker but does NOT validate at runtime unless `validate: true`. |
+| `returns`     | `{ kind: ReplyKind, data?: Record<string, 'string' \| 'number' \| 'boolean'> }` | Declare the reply kind. Enforced: the handler must call the matching reply method or the SDK throws (see Reply-kind enforcement below).           |
+| `validate`    | `boolean`                                  | When `true`, the SDK validates `ctx.args` against the declared `args` before running your handler. A bad dispatch is rejected with a structured `invalid_args` error. Also narrows TypeScript types: `required` fields become typed-present in `ctx.args`. Without `validate`, all arg fields are typed optional. |
+| `streaming`   | `boolean`                                  | Override the bot-level streaming flag for this command only.                                                                                     |
+| `mimeType`    | `string`                                   | MIME-type hint advertised in IDENTIFY (advertising-only, doesn't affect runtime).                                                                |
+
+#### `ArgSpec` shape
+
+```ts
+interface ArgSpec {
+  type: 'string' | 'number' | 'boolean' | 'enum';
+  required?: boolean;
+  description?: string;
+  values?: readonly string[];   // required when type === 'enum'
+}
+```
+
+#### `returns.kind` vocabulary
+
+`'text'` | `'list'` | `'table'` | `'image'` | `'buttons'` | `'collect'`
+
+The declared kind is **enforced at runtime**: if the handler calls a reply method that doesn't match the declaration (e.g. `returns: { kind: 'list' }` but the handler calls `ctx.reply()`), the SDK throws a hard error. TypeScript also narrows `ctx`'s available reply methods to just the ones valid for the declared kind.
+
+#### Example
+
+```ts
+bot.cmd({
+  name: 'topic',
+  description: 'Scrape trends for a query, then pick one',
+  args: {
+    query:  { type: 'string', required: true, description: 'Search query' },
+    format: { type: 'string', description: 'e.g. short_30s' },
+    voice:  { type: 'enum', values: ['on', 'off'] },
+  },
+  returns: { kind: 'list', data: { jobId: 'string', state: 'string' } },
+  validate: false,   // opt-in: when true, args are validated AND required fields typed-present
+}, async (ctx) => {
+  // ctx.args is typed from `args`; ctx reply methods are narrowed to returns.kind
+  await ctx.replyList([{ title: ctx.args.query ?? '' }]);
+});
+```
+
+Handler receives a `CommandContext`:
 
 ```ts
-bot.cmd('greet', async (ctx) => {
-  // ctx.args:  parsed args from the consumer
+bot.cmd({ name: 'greet' }, async (ctx) => {
+  // ctx.args:    parsed args from the consumer
   // ctx.command: 'greet'
-  // ctx.msgId: unique id for this invocation
+  // ctx.msgId:   unique id for this invocation
 
   await ctx.reply({ text: `Hello, ${ctx.args.name ?? 'world'}!` });
 
@@ -92,7 +140,7 @@ The gateway pings the bot every 30 seconds and the SDK responds. If the gateway
 A reply can carry a `dispatch` directive to chain a command to another bot:
 
 ```js
-bot.cmd('summary', async (ctx) => {
+bot.cmd({ name: 'summary' }, async (ctx) => {
   await ctx.reply({
     text: 'fetching price first…',
     dispatch: { to: 'price-bot', command: 'price', args: { ticker: 'AAPL' } },
@@ -107,11 +155,14 @@ Chains run up to depth 5 with loop detection. The original consumer pays for eve
 By default `ctx.reply({ text })` sends a plain-text body — the consumer
 renders it as text. To get richer rendering (source-badge lists, striped
 tables) on the dashboard Test Console and the public Try widget, return a
-**kinded** body via the two new helpers:
+**kinded** body via the helpers:
 
 ```js
 // List output
-bot.cmd('headlines', async (ctx) => {
+bot.cmd({
+  name: 'headlines',
+  returns: { kind: 'list' },
+}, async (ctx) => {
   await ctx.replyList(
     [
       { label: 'AP',     title: 'Story one', secondary: '2m', href: '…' },
@@ -122,7 +173,10 @@ bot.cmd('headlines', async (ctx) => {
 });
 
 // Table output
-bot.cmd('top5', async (ctx) => {
+bot.cmd({
+  name: 'top5',
+  returns: { kind: 'table' },
+}, async (ctx) => {
   await ctx.replyTable({
     headers: ['ticker', 'price', 'change'],
     rows: [
@@ -159,10 +213,11 @@ guard flips, so if you catch the error you can still send a corrected
 further reply calls throw — the SDK guarantees exactly-one reply per
 command.
 
-**Pair with `output_kind`.** Declare the shape of each command on the bot
-detail page so the dashboard can pick the right renderer ahead of time
-(`text` / `list` / `table`). Mis-declarations soft-fall-back to text
-rendering — they don't fail the dispatch.
+**Reply-kind enforcement.** When `returns.kind` is declared on the command
+definition, the SDK enforces it at runtime: calling a mismatched reply
+method (e.g. `ctx.reply()` when `returns: { kind: 'list' }`) throws a hard
+error. TypeScript also narrows `ctx`'s available reply methods to the ones
+valid for the declared kind, so mismatches are caught at compile time.
 
 ## Streaming progress (`ctx.update`)
 
@@ -175,7 +230,7 @@ const bot = new Bot({
   streaming: true,             // enables ctx.update across all commands
 });
 
-bot.cmd('analyze', async (ctx) => {
+bot.cmd({ name: 'analyze' }, async (ctx) => {
   await ctx.update({ progress: 10, text: 'Fetching…' });
   await ctx.update({ progress: 60, text: 'Crunching…' });
   await ctx.reply({
@@ -186,11 +241,11 @@ bot.cmd('analyze', async (ctx) => {
 });
 ```
 
-Or per-command:
+Or per-command using `streaming` in the definition:
 
 ```js
-bot.cmd('analyze', { streaming: true }, async (ctx) => { /* … */ });
-bot.cmd('ping', async (ctx) => { /* no ctx.update here */ });
+bot.cmd({ name: 'analyze', streaming: true }, async (ctx) => { /* … */ });
+bot.cmd({ name: 'ping' }, async (ctx) => { /* no ctx.update here */ });
 ```
 
 **Progress shapes** (use whichever fits the work):
@@ -218,15 +273,15 @@ Tell the platform what each command's reply looks like so the bot
 detail page can show consumers what to expect:
 
 ```js
-bot.cmd('chart', { streaming: true, mimeType: 'image/png' }, async (ctx) => {
+bot.cmd({ name: 'chart', streaming: true, mimeType: 'image/png' }, async (ctx) => {
   await ctx.reply({ data: chartBytes, mimeType: 'image/png' });
 });
 
-bot.cmd('summarize', { mimeType: 'text/markdown' }, async (ctx) => {
+bot.cmd({ name: 'summarize', mimeType: 'text/markdown' }, async (ctx) => {
   await ctx.reply({ text: '# Summary\n…', mimeType: 'text/markdown' });
 });
 
-bot.cmd('ping', async (ctx) => {   // no opts — displays as text/plain
+bot.cmd({ name: 'ping' }, async (ctx) => {   // no mimeType — displays as text/plain
   await ctx.reply({ text: 'pong' });
 });
 ```
@@ -267,8 +322,7 @@ v0.4 is additive — nothing breaks for bots calling only `ctx.reply()`.
 New surface:
 
 - `new Bot({ …, streaming: true })` to enable `ctx.update()`
-- `bot.cmd(name, { streaming: true }, handler)` to flip the flag per
-  command without touching bot-init
+- `streaming: true` inside the command definition to flip the flag per command
 - `ctx.update({ progress?, text?, data?, mimeType? })` — send 1+
   intermediate frames before `ctx.reply()`
 - `mimeType` on `ctx.reply()` for the existing final-reply path
@@ -277,11 +331,25 @@ No env-var changes, no protocol breakage, no upstream re-auth.
 
 ## v0.4.0 → v0.4.1 (per-command mimeType)
 
-Additive — no breaking changes. The `mimeType?` field in
-`CommandHandlerOptions` is optional; bots that ignore it work exactly
-the same. The SDK auto-builds an IDENTIFY-time `commands` array from
-your registered handlers so the platform can display them on the bot
-detail page.
+Additive — no breaking changes. The `mimeType?` field in the command definition
+is optional; bots that ignore it work exactly the same. The SDK auto-builds an
+IDENTIFY-time `commands` array from your registered handlers so the platform can
+display them on the bot detail page.
+
+## v0.14 → v0.15 (object `cmd()`)
+
+**Breaking.** See [MIGRATION.md](./MIGRATION.md) for the full guide.
+
+`cmd()` now takes a **command definition object** as its first argument. The
+string-form is removed.
+
+```diff
+- bot.cmd("ping", async (ctx) => { … })
++ bot.cmd({ name: "ping" }, async (ctx) => { … })
+
+- bot.cmd("analyze", { streaming: true }, async (ctx) => { … })
++ bot.cmd({ name: "analyze", streaming: true }, async (ctx) => { … })
+```
 
 ## License
 

package/dist/argSchema.d.ts

@@ -0,0 +1,7 @@
+import { type ZodType } from 'zod';
+import type { ArgSpec, ReturnsSpec } from './types.js';
+export declare function argsToJsonSchema(args: Record<string, ArgSpec>): Record<string, unknown>;
+export declare function returnsDataToJsonSchema(data: ReturnsSpec['data']): Record<string, unknown> | undefined;
+export declare function returnsDataToZod(data: ReturnsSpec['data']): ZodType | undefined;
+export declare function argsToZod(args: Record<string, ArgSpec>): ZodType;
+//# sourceMappingURL=argSchema.d.ts.map

package/dist/argSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argSchema.d.ts","sourceRoot":"","sources":["../src/argSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAK,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAavD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUvF;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAKrC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,GAAG,SAAS,CAO/E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAkBhE"}

package/dist/argSchema.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+function propSchema(s) {
+    if (s.type === 'enum') {
+        const p = { type: 'string', enum: [...(s.values ?? [])] };
+        if (s.description)
+            p.description = s.description;
+        return p;
+    }
+    const p = { type: s.type };
+    if (s.description)
+        p.description = s.description;
+    return p;
+}
+export function argsToJsonSchema(args) {
+    const properties = {};
+    const required = [];
+    for (const [name, spec] of Object.entries(args)) {
+        properties[name] = propSchema(spec);
+        if (spec.required)
+            required.push(name);
+    }
+    const out = { type: 'object', properties };
+    if (required.length)
+        out.required = required;
+    return out;
+}
+export function returnsDataToJsonSchema(data) {
+    if (!data)
+        return undefined;
+    const properties = {};
+    for (const [name, t] of Object.entries(data))
+        properties[name] = { type: t };
+    return { type: 'object', properties };
+}
+export function returnsDataToZod(data) {
+    if (!data)
+        return undefined;
+    const shape = {};
+    for (const [name, t] of Object.entries(data)) {
+        shape[name] = t === 'number' ? z.number() : t === 'boolean' ? z.boolean() : z.string();
+    }
+    return z.object(shape);
+}
+export function argsToZod(args) {
+    const shape = {};
+    for (const [name, spec] of Object.entries(args)) {
+        if (spec.type === 'enum' && (!spec.values || spec.values.length === 0)) {
+            throw new Error(`enum arg requires a non-empty \`values\` array`);
+        }
+        let field = spec.type === 'string'
+            ? z.string()
+            : spec.type === 'number'
+                ? z.number()
+                : spec.type === 'boolean'
+                    ? z.boolean()
+                    : z.enum([...(spec.values ?? [])]);
+        if (!spec.required)
+            field = field.optional();
+        shape[name] = field;
+    }
+    return z.object(shape);
+}
+//# sourceMappingURL=argSchema.js.map

package/dist/argSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argSchema.js","sourceRoot":"","sources":["../src/argSchema.ts"],"names":[],"mappings":"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"}

package/dist/bot.d.ts

@@ -1,5 +1,5 @@
 import { nanoid } from 'nanoid';
-import type { BotOptions, CommandHandler, CommandHandlerOptions } from './types.js';
+import type { ArgsOf, BotOptions, CommandContext, CommandDef, CommandHandler, ReturnsOf } from './types.js';
 export { SDK_PACKAGE_VERSION } from './version.js';
 export declare class Bot {
     private readonly opts;
@@ -18,10 +18,10 @@ export declare class Bot {
     private reconnectAttempt;
     private cachedApiKey;
     constructor(opts: BotOptions);
-    /** Register a handler with no per-command overrides. */
-    cmd(name: string, handler: CommandHandler): this;
-    /** Register a handler with per-command overrides. */
-    cmd(name: string, opts: CommandHandlerOptions, handler: CommandHandler): this;
+    /** Register a command from its definition object. The ONLY public way to add a command. */
+    cmd<const D extends CommandDef>(def: D, handler: (ctx: CommandContext<ArgsOf<D>, ReturnsOf<D>>) => void | Promise<void>): this;
+    /** Internal: the single registration path. Not part of the public API. */
+    private registerHandler;
     /** Register an internal action handler (Interactive Prompts). Stored in the
      *  same handler map `cmd()` uses — so dispatch routing is unchanged — but
      *  flagged `internal: true` so it is EXCLUDED from the IDENTIFY advertised

package/dist/bot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAShC,OAAO,KAAK,EACV,UAAU,EAIV,cAAc,EACd,qBAAqB,EAMtB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AA8CnD,qBAAa,GAAG;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAG1B;IACF,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,YAAY,CAAuB;gBAE/B,IAAI,EAAE,UAAU;IA2C5B,wDAAwD;IACxD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAChD,qDAAqD;IACrD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IA0B7E;;;;wEAIoE;IACpE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAIjD,OAAO,CAAC,cAAc;IAMtB,2FAA2F;IACrF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB9B,iFAAiF;YACnE,aAAa;IAuD3B,OAAO,CAAC,iBAAiB;YAcX,YAAY;IAe1B;;;;;OAKG;YACW,aAAa;IAoB3B,0DAA0D;IACpD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBjC;;yEAEqE;IACrE,OAAO,CAAC,oBAAoB;YAYd,QAAQ;IA6EtB,OAAO,CAAC,oBAAoB;IAQ5B,4EAA4E;IAC5E,OAAO,CAAC,kBAAkB;IAc1B;;iBAEa;IACb,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,WAAW;IAuUnB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,UAAU;CAQnB;AAGD,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAWhC,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EAGV,cAAc,EACd,UAAU,EACV,cAAc,EAMd,SAAS,EAGV,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AA8CnD,qBAAa,GAAG;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAG1B;IACF,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,YAAY,CAAuB;gBAE/B,IAAI,EAAE,UAAU;IA2C5B,2FAA2F;IAC3F,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,EAC5B,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC9E,IAAI;IAiCP,0EAA0E;IAC1E,OAAO,CAAC,eAAe;IASvB;;;;wEAIoE;IACpE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAIjD,OAAO,CAAC,cAAc;IAMtB,2FAA2F;IACrF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB9B,iFAAiF;YACnE,aAAa;IAmE3B,OAAO,CAAC,iBAAiB;YAcX,YAAY;IAe1B;;;;;OAKG;YACW,aAAa;IAoB3B,0DAA0D;IACpD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBjC;;yEAEqE;IACrE,OAAO,CAAC,oBAAoB;YAYd,QAAQ;IAgGtB,OAAO,CAAC,oBAAoB;IAQ5B,4EAA4E;IAC5E,OAAO,CAAC,kBAAkB;IAc1B;;iBAEa;IACb,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,WAAW;IA2WnB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,UAAU;CAQnB;AAGD,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/bot.js

@@ -7,6 +7,8 @@ import { readCredentialFor, writeCredentialFor } from './credentials.js';
 import { runDeviceFlow } from './sso.js';
 import { CollectStore } from './collectStore.js';
 import { closeDueByTime, makeSubmitHandler } from './collect.js';
+import { toJsonSchema } from './jsonSchema.js';
+import { argsToJsonSchema, returnsDataToJsonSchema, argsToZod, returnsDataToZod } from './argSchema.js';
 // Version constant is generated from package.json at build time by
 // scripts/generate-version.mjs — keeps the IDENTIFY-frame `sdkVersion`
 // field in sync with the published npm version instead of relying on a
@@ -93,19 +95,57 @@ export class Bot {
         // touch sqlite.
         this.action('__collect_submit', (ctx) => makeSubmitHandler(this.ensureCollectStore(), this.collectSink())(ctx));
     }
-    cmd(name, handlerOrOpts, maybeHandler) {
-        if (this.transport) {
-            throw new Error('cmd() must be called before connect()');
+    /** Register a command from its definition object. The ONLY public way to add a command. */
+    cmd(def, handler) {
+        if (typeof def === 'string' || def === null || typeof def !== 'object') {
+            throw new Error("cmd() takes a command object, e.g. cmd({ name: 'x' }, handler)");
         }
-        if (this.handlers.has(name)) {
-            throw new Error(`duplicate handler for command ${name}`);
+        if (!def.name || typeof def.name !== 'string') {
+            throw new Error('cmd() command object requires a string `name`');
         }
-        // Disambiguate overloads
-        const opts = typeof handlerOrOpts === 'function' ? {} : handlerOrOpts;
-        const handler = typeof handlerOrOpts === 'function' ? handlerOrOpts : maybeHandler;
-        if (typeof handler !== 'function') {
-            throw new Error(`cmd('${name}') missing handler function`);
+        const opts = {};
+        if (def.streaming !== undefined)
+            opts.streaming = def.streaming;
+        if (def.mimeType !== undefined)
+            opts.mimeType = def.mimeType;
+        if (def.description !== undefined)
+            opts.description = def.description;
+        // Advertise: args descriptor → inputSchema (args wins over legacy input zod).
+        if (def.args)
+            opts.advertiseInput = argsToJsonSchema(def.args);
+        else if (def.input)
+            opts.advertiseInput = toJsonSchema(def.input);
+        // returns → outputKind + outputSchema (returns wins over legacy output zod).
+        if (def.returns) {
+            opts.outputKind = def.returns.kind;
+            const outputSchema = returnsDataToJsonSchema(def.returns.data);
+            if (outputSchema !== undefined)
+                opts.advertiseOutput = outputSchema;
+            // Wire returns.data into the existing warn-only check path (L567).
+            const warnZod = returnsDataToZod(def.returns.data);
+            if (warnZod)
+                opts.output = warnZod;
         }
+        else if (def.output) {
+            opts.advertiseOutput = toJsonSchema(def.output);
+            // Keep opts.output for the warn-only output validation in makeContext.
+            opts.output = def.output;
+        }
+        // Validate path: only when explicitly opted in, and only for the args descriptor.
+        if (def.validate && def.args)
+            opts.argsZod = argsToZod(def.args);
+        else if (def.input)
+            opts.argsZod = def.input; // legacy zod validates as before
+        return this.registerHandler(def.name, opts, handler);
+    }
+    /** Internal: the single registration path. Not part of the public API. */
+    registerHandler(name, opts, handler) {
+        if (this.transport)
+            throw new Error('cmd()/action() must be called before connect()');
+        if (this.handlers.has(name))
+            throw new Error(`duplicate handler for command ${name}`);
+        if (typeof handler !== 'function')
+            throw new Error(`handler for ${name} must be a function`);
         this.handlers.set(name, handler);
         this.cmdOpts.set(name, opts);
         return this;
@@ -116,7 +156,7 @@ export class Bot {
      *  command list (capability advertising / marketplace / `commands`
      *  introspection). An action is simply a non-advertised command. */
     action(id, handler) {
-        return this.cmd(id, { internal: true }, handler);
+        return this.registerHandler(id, { internal: true }, handler);
     }
     isStreamingFor(commandName) {
         const cmdLevel = this.cmdOpts.get(commandName)?.streaming;
@@ -163,10 +203,17 @@ export class Bot {
             const entry = {
                 name,
                 streaming,
+                description: opts.description ?? '',
             };
             if (typeof opts.mimeType === 'string' && opts.mimeType.length > 0) {
                 entry.mimeType = opts.mimeType;
             }
+            if (opts.advertiseInput)
+                entry.inputSchema = opts.advertiseInput;
+            if (opts.advertiseOutput)
+                entry.outputSchema = opts.advertiseOutput;
+            if (opts.outputKind)
+                entry.outputKind = opts.outputKind;
             return entry;
         });
         const transport = new Transport({
@@ -299,7 +346,7 @@ export class Bot {
         this.recordSeen(cmd.msgId);
         const handler = this.handlers.get(cmd.command);
         const streaming = this.isStreamingFor(cmd.command);
-        const ctx = this.makeContext(cmd, streaming);
+        const { ctx, replyError } = this.makeContext(cmd, streaming);
         // Built-in `commands` fallback — only used if the bot didn't register
         // its own. Lets every bot answer "what can you do?" without ceremony.
         if (!handler && cmd.command === 'commands') {
@@ -335,6 +382,24 @@ export class Bot {
             }
             return;
         }
+        // Input validation: a declared zod schema (argsZod from cmd() or legacy input)
+        // rejects a malformed dispatch with a structured error and never runs the handler.
+        const inputSchema = this.cmdOpts.get(cmd.command)?.argsZod;
+        if (inputSchema) {
+            const parsed = inputSchema.safeParse(ctx.args);
+            if (!parsed.success) {
+                try {
+                    replyError({
+                        text: `Invalid arguments for ${cmd.command}: ${parsed.error.message}`,
+                        data: { error: 'invalid_args', issues: parsed.error.issues },
+                    });
+                }
+                catch (err) {
+                    logError('invalid-args reply failed:', err);
+                }
+                return;
+            }
+        }
         try {
             await handler(ctx);
         }
@@ -342,10 +407,11 @@ export class Bot {
             logError('command handler error:', err);
             // If the handler threw before sending a reply, send a structured error
             // frame so the consumer doesn't time out waiting for a reply that will
-            // never arrive. ctx.reply() itself throws if already called — swallow
-            // that case.
+            // never arrive. replyError bypasses kind enforcement (this is an SDK
+            // diagnostic frame, not a handler reply) but still runs the double-reply
+            // guard — so if the handler already replied, we silently skip.
             try {
-                await ctx.reply({
+                replyError({
                     text: `handler threw: ${err instanceof Error ? err.message : String(err)}`,
                 });
             }
@@ -405,6 +471,13 @@ export class Bot {
     makeContext(cmd, streaming) {
         let replied = false;
         const transport = this.transport;
+        const outputSchema = this.cmdOpts.get(cmd.command)?.output;
+        const declaredKind = this.cmdOpts.get(cmd.command)?.outputKind;
+        const assertKind = (actual) => {
+            if (declaredKind && declaredKind !== actual) {
+                throw new Error(`command ${cmd.command} declared returns.kind='${declaredKind}' but sent a '${actual}' reply`);
+            }
+        };
         // Interactive Prompts: the server injects the answering user's id as the
         // reserved `args._user`. Lift it onto ctx.user and strip it from ctx.args
         // so handlers never see the reserved key. Undefined for normal commands.
@@ -437,7 +510,17 @@ export class Bot {
             ...(answeringUser ? { user: answeringUser } : {}),
             msgId: cmd.msgId,
             reply: async (body) => {
+                assertKind((body.kind ?? 'text'));
                 guardReply();
+                // Warn-only output validation: a declared output schema that the
+                // structured `data` violates logs a warning but NEVER blocks the
+                // user-facing reply — schema drift must not break a response.
+                if (outputSchema) {
+                    const res = outputSchema.safeParse(body.data);
+                    if (!res.success) {
+                        logWarn(`output for ${cmd.command} does not match its declared schema (sending anyway): ${res.error.message}`);
+                    }
+                }
                 // guardReply throws if transport is null, so the non-null assertion
                 // below is safe — TypeScript can't see through the closure.
                 transport.sendReply(cmd.msgId, body);
@@ -457,6 +540,7 @@ export class Bot {
                 if (header !== undefined && typeof header !== 'string') {
                     throw new Error(`replyList() header must be a string when provided (msgId=${cmd.msgId})`);
                 }
+                assertKind('list');
                 guardReply();
                 const body = {
                     kind: 'list',
@@ -485,6 +569,7 @@ export class Bot {
                         throw new Error(`replyTable() row[${r}] has ${Array.isArray(row) ? row.length : 'non-array'} cell(s), expected ${cols} (msgId=${cmd.msgId})`);
                     }
                 }
+                assertKind('table');
                 guardReply();
                 const out = {
                     kind: 'table',
@@ -516,6 +601,7 @@ export class Bot {
                 if (!base64) {
                     throw new Error(`replyImage() requires non-empty image data (msgId=${cmd.msgId})`);
                 }
+                assertKind('image');
                 guardReply();
                 const out = {
                     kind: 'image',
@@ -542,6 +628,7 @@ export class Bot {
                         throw new Error(`replyButtons() button[${i}] is missing a non-empty action (msgId=${cmd.msgId})`);
                     }
                 }
+                assertKind('buttons');
                 guardReply();
                 const out = {
                     kind: 'buttons',
@@ -640,6 +727,7 @@ export class Bot {
                     until,
                     origin: { msgId: cmd.msgId },
                 });
+                assertKind('collect');
                 guardReply();
                 transport.sendReply(cmd.msgId, {
                     kind: 'collect',
@@ -675,7 +763,15 @@ export class Bot {
                 transport.sendUpdate(cmd.msgId, progress, body);
             };
         }
-        return ctx;
+        // Internal sender for SDK-generated error/diagnostic frames (invalid_args,
+        // handler-threw recovery). Bypasses assertKind — kind enforcement is a
+        // contract on the HANDLER's reply, not on SDK infrastructure frames — but
+        // still runs guardReply so double-reply protection stays intact.
+        const replyError = (body) => {
+            guardReply();
+            transport.sendReply(cmd.msgId, body);
+        };
+        return { ctx, replyError };
     }
     isDuplicate(msgId) {
         return this.seen.has(msgId);