@wabot-dev/framework 0.9.80 → 2.0.0-beta.0

package/dist/src/ui/index.js

@@ -0,0 +1,29 @@
+import { container } from '../core/injection/index.js';
+export { uiController } from '../feature/ui-controller/metadata/@uiController.js';
+export { view } from '../feature/ui-controller/metadata/@view.js';
+export { action } from '../feature/ui-controller/metadata/@action.js';
+export { uiMiddleware } from '../feature/ui-controller/metadata/@uiMiddleware.js';
+export { UiControllerMetadataStore } from '../feature/ui-controller/metadata/UiControllerMetadataStore.js';
+import { UiRendererRegistry } from '../feature/ui-controller/renderer/UiRendererRegistry.js';
+export { ISLAND_MARKER, getIslandMeta, isIsland, island, setIslandId } from '../feature/ui-controller/island/island.js';
+export { deserializeProps, serializeProps } from '../feature/ui-controller/island/serialize.js';
+export { ISLAND_FILE_PATTERN, IslandRegistry, isIslandFile, toIslandId } from '../feature/ui-controller/island/IslandRegistry.js';
+export { renderDocument } from '../feature/ui-controller/document/renderDocument.js';
+export { REDIRECT_MARKER, isRedirect, redirect } from '../feature/ui-controller/document/helpers.js';
+export { escapeAttr, escapeHtml } from '../feature/ui-controller/document/escape.js';
+export { actionUrl, callAction } from '../feature/ui-controller/actions.js';
+export { registerUiControllers, runUiControllers } from '../feature/ui-controller/runUiControllers.js';
+import { PreactRenderer } from '../addon/ui/preact/PreactRenderer.js';
+export { Outlet } from '../addon/ui/preact/outlet.js';
+export { Fragment, cloneElement, createContext, h as createElement, createRef, h, isValidElement, toChildArray } from 'preact';
+export * from 'preact/hooks';
+export { Signal, batch, computed, createModel, effect, signal, action as signalAction, untracked, useComputed, useModel, useSignal, useSignalEffect } from '@preact/signals';
+
+// UI entrypoint: import from '@wabot-dev/framework/ui'.
+//
+// Importing this module registers Preact + @preact/signals as the default UI
+// renderer. Configure your tsconfig with:
+//   "jsx": "react-jsx", "jsxImportSource": "@wabot-dev/framework/ui"
+container.resolve(UiRendererRegistry).setDefault(new PreactRenderer());
+
+export { UiRendererRegistry };

package/dist/src/ui/jsx-dev-runtime.d.ts

@@ -0,0 +1 @@
+export * from 'preact/jsx-dev-runtime';

package/dist/src/ui/jsx-dev-runtime.js

@@ -0,0 +1 @@
+export * from 'preact/jsx-dev-runtime';

package/dist/src/ui/jsx-runtime.d.ts

@@ -0,0 +1 @@
+export * from 'preact/jsx-runtime';

package/dist/src/ui/jsx-runtime.js

@@ -0,0 +1 @@
+export * from 'preact/jsx-runtime';

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@wabot-dev/framework",
-  "version": "0.9.80",
+  "version": "2.0.0-beta.0",
   "description": "Framework for IA Chat Bots",
   "type": "module",
   "main": "dist/src/index.js",
   "module": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
+  "bin": {
+    "wabot-skills": "./bin/wabot-skills.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/src/index.d.ts",
@@ -14,6 +17,19 @@
     "./testing": {
       "types": "./dist/src/testing/index.d.ts",
       "import": "./dist/src/testing/index.js"
+    },
+    "./ui": {
+      "types": "./dist/src/ui/index.d.ts",
+      "browser": "./dist/src/ui/client.js",
+      "import": "./dist/src/ui/index.js"
+    },
+    "./ui/jsx-runtime": {
+      "types": "./dist/src/ui/jsx-runtime.d.ts",
+      "import": "./dist/src/ui/jsx-runtime.js"
+    },
+    "./ui/jsx-dev-runtime": {
+      "types": "./dist/src/ui/jsx-dev-runtime.d.ts",
+      "import": "./dist/src/ui/jsx-dev-runtime.js"
     }
   },
   "license": "MIT",
@@ -44,27 +60,25 @@
     "async-jobs",
     "cron",
     "messaging-platforms",
+    "slack",
     "bot-framework",
     "conversational-ai"
   ],
   "files": [
     "dist/src",
     "dist/build",
+    "bin",
+    "skills",
     "LICENSE.md"
   ],
   "scripts": {
-    "build": "rollup --config rollup.config.ts --configPlugin typescript && tsup --dts-only --format esm --out-dir dist/src src/index.ts && tsup --dts-only --format esm --out-dir dist/src/testing src/testing/index.ts",
+    "build": "rollup --config rollup.config.ts --configPlugin typescript && tsup --dts-only --format esm --out-dir dist/src src/index.ts && tsup --dts-only --format esm --out-dir dist/src/testing src/testing/index.ts && tsup --dts-only --format esm --out-dir dist/src/ui src/ui/index.ts && tsup --dts-only --format esm --out-dir dist/src/ui src/ui/jsx-runtime.ts && tsup --dts-only --format esm --out-dir dist/src/ui src/ui/jsx-dev-runtime.ts",
     "test:units": "node --import @yucacodes/ts  --test './src/**/*.unit.test.ts'",
     "test:integration": "node --import @yucacodes/ts --import ./env.mjs  --test './src/**/*.integration.test.ts'",
     "test:multiprocess": "node --import @yucacodes/ts --import ./env.mjs  --test './src/**/*.multiprocess.test.ts'",
-    "test:elia": "node --import @yucacodes/ts --test './test/elia/**/*.unit.test.ts'",
-    "test:elia:eval": "node --import @yucacodes/ts --import ./env.mjs --test './test/elia/**/*.eval.test.ts'",
     "fmt": "prettier --write .",
     "fmt:check": "prettier --check .",
-    "types:check": "tsc --noEmit",
-    "elia:dev": "node --import @yucacodes/ts --import ./env.mjs  ./test/elia/_run_.ts",
-    "elia:watch": "node --watch --import @yucacodes/ts --import ./env.mjs  ./test/elia/_run_.ts",
-    "elia:cmd": "node --import @yucacodes/ts ./test/elia/_cmd_.ts"
+    "types:check": "tsc --noEmit"
   },
   "devDependencies": {
     "@rollup/plugin-alias": "5.1.1",
@@ -81,8 +95,10 @@
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.60.0",
+    "@slack/bolt": "^3.17.0",
     "@google/genai": "^1.16.0",
     "@openrouter/sdk": "^0.12.2",
+    "@preact/signals": "^2.9.2",
     "@types/big.js": "^6.2.2",
     "@types/debug": "^4.1.12",
     "@types/express": "^5.0.1",
@@ -90,28 +106,32 @@
     "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "22.14.1",
     "@types/pg": "^8.11.14",
-    "@yucacodes/ts": "0.0.8",
+    "@yucacodes/ts": "^0.1.0",
     "big.js": "^7.0.1",
     "body-parser": "^2.2.0",
     "cron-parser": "^5.4.0",
     "debug": "^4.4.0",
     "dotenv": "^16.5.0",
+    "esbuild": "^0.25.12",
     "express": "^5.1.0",
     "grammy": "^1.36.0",
     "html-to-text": "^9.0.5",
     "jsonwebtoken": "^9.0.2",
     "openai": "^6.10.0",
     "pg": "^8.15.6",
+    "preact": "^10.29.3",
+    "preact-render-to-string": "^6.7.0",
+    "prettier": "^3.5.3",
     "reflect-metadata": "^0.2.2",
     "short-uuid": "^6.0.3",
     "socket.io": "^4.8.1",
     "socket.io-client": "^4.8.1",
     "tslib": "^2.8.1",
-    "tsyringe": "^4.9.1",
-    "uuid": "^14.0.0",
-    "wasenderapi": "^0.1.5",
+    "@hubspot/api-client": "^13.5.0",
     "tsup": "^8.4.0",
+    "tsyringe": "^4.9.1",
     "typescript": "^6.0.3",
-    "prettier": "^3.5.3"
+    "uuid": "^14.0.0",
+    "wasenderapi": "^0.1.5"
   }
 }

package/skills/wabot-async/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: wabot-async
+description: Use when running background work in Wabot — fire-and-forget commands, scheduled deferred commands, cron handlers, or wrapping side-effectful methods in a DB transaction. Covers @command, @commandHandler, @cronHandler, @transaction, the Async service (runCommand, scheduleCommand, IScheduleAt), ICommandHandler / ICronHandler, and how the in-memory vs PG job/cron stores are wired by the project runner.
+---
+
+# Async commands, cron, and transactions
+
+Wabot's async layer handles three kinds of work:
+
+- **Commands** — typed messages with a registered handler. Run immediately (`runCommand`) or scheduled (`scheduleCommand`).
+- **Crons** — handlers that fire on a cron expression.
+- **Transactions** — wrap a method so all repository writes happen inside one DB transaction per registered adapter.
+
+The job store, cron job store, and transaction adapter are auto-selected by the project runner based on `DATABASE_URL` (in-memory ↔ PostgreSQL). No manual registration.
+
+## Commands
+
+A command is a plain class decorated with `@command(name)`. Fields use the standard validators from `wabot-validation`.
+
+```typescript
+import { command, isNumber, isString, min } from '@wabot-dev/framework'
+
+@command('orders.charge')
+export class ChargeOrder {
+  @isString() orderId!: string
+  @isNumber() @min(1) amountCents!: number
+}
+```
+
+The handler implements `ICommandHandler<C>` and is bound with `@commandHandler(Command)`:
+
+```typescript
+import { commandHandler, ICommandHandler, injectable } from '@wabot-dev/framework'
+import { ChargeOrder } from './ChargeOrder'
+
+@commandHandler(ChargeOrder)
+export class ChargeOrderHandler implements ICommandHandler<ChargeOrder> {
+  constructor(private payments: PaymentService) {}
+
+  async handle(cmd: ChargeOrder) {
+    await this.payments.charge(cmd.orderId, cmd.amountCents)
+  }
+}
+```
+
+Trigger it with the `Async` singleton:
+
+```typescript
+import { Async, container } from '@wabot-dev/framework'
+
+const async = container.resolve(Async)
+
+// Run as soon as a worker is free
+await async.runCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 })
+
+// Schedule for later: absolute Date or relative delay
+await async.scheduleCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 }, { minutes: 30 })
+await async.scheduleCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 }, new Date('2026-12-31T08:00:00Z'))
+```
+
+`IScheduleAt = Date | { seconds: number } | { minutes: number } | { hours: number } | { days: number }`.
+
+`Async.runCommand` returns a `Job` immediately (it has an `id` you can persist). The payload is validated against the command class before the job is stored — bad shapes throw `CustomError`.
+
+`@commandHandler` applies `@injectable()`. There is at most one handler per command name; registering a second throws.
+
+## Cron handlers
+
+```typescript
+import { cronHandler, ICronHandler } from '@wabot-dev/framework'
+
+@cronHandler({ name: 'daily-cleanup', cron: '0 3 * * *' })
+export class DailyCleanup implements ICronHandler {
+  constructor(private games: GameRepository) {}
+
+  async handle() {
+    // ...
+  }
+
+  // Optional. Called when handle() throws.
+  async handleError(err: any) {
+    // ...
+  }
+}
+```
+
+- `cron` accepts standard 5-field or 6-field (with seconds) cron expressions.
+- `disabled: true` turns a handler off without removing it (useful for guarded rollouts).
+- `@cronHandler` applies `@singleton()` automatically — do not stack lifecycle decorators.
+
+The runner registers these into `CronScheduler`, which persists per-cron state in `CronJobRepository` so missed runs aren't replayed on restart.
+
+## Transactions
+
+`@transaction(dbNames?)` wraps an async method so every adapter listed runs the call inside a transaction. Without arguments, all registered adapters participate (today there is one: the runner registers `PgTransactionAdapter` under the name `'default'` when `DATABASE_URL` is Postgres).
+
+```typescript
+import { transaction } from '@wabot-dev/framework'
+
+@injectable()
+export class Checkout {
+  @transaction()
+  async checkout(orderId: string) {
+    await this.orderRepository.update(...)
+    await this.paymentRepository.create(...)
+  }
+}
+```
+
+Behavior:
+- Repository writes performed inside the method go to the same client/connection.
+- Throwing rolls back; returning commits.
+- Nested `@transaction`-decorated calls reuse the outer transaction (no nested begin).
+- Without Postgres no adapter is registered, so `@transaction()` just executes the method (no wrap). Naming a specific adapter (e.g. `@transaction(['default'])`) throws at call time if it isn't registered — never write `@transaction(['pg'])`.
+
+## Manual run / stop
+
+In production the runner discovers and starts everything. For testing or custom hosts:
+
+```typescript
+import { runCommandHandlers, runCronHandlers, stopCommandHandlers, stopCronHandlers } from '@wabot-dev/framework'
+
+runCommandHandlers([ChargeOrderHandler])
+runCronHandlers([DailyCleanup])
+
+// later
+stopCommandHandlers([ChargeOrderHandler])
+stopCronHandlers([DailyCleanup])
+```
+
+`testAsync` is exported for integration tests against the real job/cron schedulers — see `wabot-ts/src/feature/async/testAsync.ts` for an example.
+
+## Rules
+
+- Command classes are *data* classes. Don't put behavior on them — that belongs in the handler.
+- Don't reuse a command name for two handlers. The framework throws on boot.
+- Don't `await async.runCommand(...)` inside a request handler expecting it to finish synchronously — `runCommand` schedules the job and returns immediately. Use `async.scheduleCommand(..., { seconds: 0 })` if you want the same fire-and-forget behavior explicitly.
+- Cron expressions in seconds (6 fields) are supported but be careful: the in-memory adapter polls fast, the PG adapter polls at a lower rate.
+- Wrap multi-repository writes in `@transaction()` rather than chaining manual `withPgTransaction` calls.
+
+## Testing
+
+`createAsyncHarness({ register?, authInfo? })` from `@wabot-dev/framework/testing` runs `@command` handlers (`harness.execute(Command, data)` — real validation, returns the transformed command) and `@cronHandler` jobs (`harness.runCron(Handler)`) inline, with no PostgreSQL or polling workers. `isValidCronSequence` and `waitUntil` help with schedule assertions. See the `wabot-testing` skill.

package/skills/wabot-auth/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: wabot-auth
+description: Use when adding authentication to a Wabot REST endpoint or Socket.IO namespace, issuing JWT access/refresh tokens, or protecting endpoints with API keys. Covers the chat/request-scoped Auth<D> service, @jwtGuard / @jwtHandshakeGuard, JwtConfig and the JWT_* env vars, Jwt.createToken / findRefreshTokenAuthInfo, JwtRefreshToken, and @apiKeyGuard / @apiKeyHandshakeGuard with PgApiKeyRepository / RemoteApiKeyRepository.
+---
+
+# Authentication
+
+Wabot's auth is request-scoped. A guard middleware verifies the credential, then writes the resolved auth info into the per-request/socket `Auth<D>` instance. Downstream code reads it with `auth.require()`.
+
+## `Auth<D>`
+
+```typescript
+import { Auth, injectable } from '@wabot-dev/framework'
+
+interface SessionInfo {
+  userId: string
+  role: 'admin' | 'user'
+}
+
+@injectable()
+export class OrdersService {
+  constructor(private auth: Auth<SessionInfo>) {}
+
+  list() {
+    const session = this.auth.require() // throws CustomError({ httpCode: 401 }) if not assigned
+    return this.repo.findByUserId(session.userId)
+  }
+}
+```
+
+`Auth` is `@scoped(Lifecycle.ContainerScoped)` and exists once per request, chat, or socket connection. Methods:
+
+- `assign(info)` — sets the auth info (used by guards). Throws if already assigned.
+- `override(info)` — replaces even when assigned (use cautiously).
+- `require()` — returns the info or throws 401.
+- `isAssigned()` / `wasOverrided()` / `clear()`.
+
+## JWT — REST
+
+```typescript
+import { jwtGuard, onGet, onPost, restController } from '@wabot-dev/framework'
+
+@restController('/account')
+export class AccountController {
+  @onGet('/me')
+  @jwtGuard()
+  async me(_, auth: Auth<SessionInfo>) {
+    return auth.require()
+  }
+}
+```
+
+`@jwtGuard()` reads `Authorization: Bearer <token>`, verifies it with `JwtConfig` (env-driven, see below), and calls `auth.assign(payload)`.
+
+## JWT — Socket
+
+```typescript
+import { jwtHandshakeGuard, socketController } from '@wabot-dev/framework'
+
+@socketController('private')
+@jwtHandshakeGuard()
+export class PrivateSocketController { /* ... */ }
+```
+
+The token is read from `socket.handshake.auth.token` first, falling back to the `Authorization` header.
+
+## Issuing tokens
+
+```typescript
+import { Auth, Jwt, JwtAccessAndRefreshTokenDto, injectable, onPost, restController } from '@wabot-dev/framework'
+
+@restController('/auth')
+export class AuthController {
+  constructor(private jwt: Jwt, private auth: Auth<SessionInfo>) {}
+
+  @onPost('/login')
+  async login(body: LoginRequest): Promise<JwtAccessAndRefreshTokenDto> {
+    const session = await this.userService.verify(body)
+    this.auth.assign(session)
+    return this.jwt.createToken({ device: body.device ?? 'unknown' })
+  }
+
+  @onPost('/refresh')
+  async refresh(body: RefreshRequest): Promise<JwtAccessAndRefreshTokenDto> {
+    const session = await this.jwt.findRefreshTokenAuthInfo(body.refreshToken)
+    this.auth.override(session)
+    return this.jwt.createToken()
+  }
+}
+```
+
+`Jwt.createToken(metadata?)`:
+- Reads the current `auth.require()` info.
+- Persists a `JwtRefreshToken` via `JwtRefreshTokenRepository`. The base class throws `Method not implemented` — the project must register an implementation: `container.registerType(JwtRefreshTokenRepository, PgJwtRefreshTokenRepository)` (table `wabot.jwt_refresh_token`), or its own.
+- Returns `{ access: { token, expiration }, refresh: { token, expiration } }`.
+
+`Jwt.findRefreshTokenAuthInfo(secret)` validates the refresh secret (hash-compare + expiration + revocation) and returns the original auth payload. Throws 401 if any check fails.
+
+### Env vars
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `JWT_SECRET` | (required) | Symmetric secret or asymmetric key used for sign/verify |
+| `JWT_ALGORITHM` | `HS256` | Any `jsonwebtoken.Algorithm` |
+| `JWT_ACCESS_EXPIRATION_SECONDS` | `600` (10 min) | Access token lifetime |
+| `JWT_REFRESH_EXPIRATION_SECONDS` | `31536000` (1 yr) | Refresh token lifetime |
+
+`JwtConfig` is `@singleton()` and reads these at boot.
+
+### Refresh-token metadata
+
+`JwtRefreshToken<D>` exposes `metadata` (the arbitrary `Record<string, string>` you passed to `createToken`), `expirationTime`, `revoke()`, and `isValidToken(secret)`. The repository exposes `findByMetadata(metadata)` so you can revoke all tokens issued to a device.
+
+## API key
+
+```typescript
+import { apiKeyGuard, apiKeyHandshakeGuard, onGet, restController, socketController } from '@wabot-dev/framework'
+
+@restController('/internal')
+export class InternalController {
+  @onGet('/health')
+  @apiKeyGuard()
+  async health() { return { ok: true } }
+}
+
+@socketController('admin')
+@apiKeyHandshakeGuard()
+export class AdminSocketController { /* ... */ }
+```
+
+The guard reads `Authorization: Api-Key <secret>` (REST) or `socket.handshake.auth.token` / the `Authorization` handshake header (socket), validates via `ApiKeyRepository`, and assigns the lookup result to `Auth`.
+
+`ApiKeyRepository` is a base class with no storage — register an implementation yourself: `container.registerType(ApiKeyRepository, PgApiKeyRepository)` (table `wabot.api_key`), or `RemoteApiKeyRepository` to delegate validation to an external service:
+
+```typescript
+import { container, ApiKeyRepository, RemoteApiKeyRepository } from '@wabot-dev/framework'
+
+container.registerType(ApiKeyRepository, RemoteApiKeyRepository)
+```
+
+Set `WABOT_API_KEY` and `WABOT_LLM_URL` to point `RemoteApiKeyRepository` at your auth service (it expects the same shape as the Wabot platform).
+
+## Rules
+
+- Always type `Auth<D>` with your session shape. `auth.require()` returns the typed value.
+- A guard runs once per request/connection. Don't reassign manually — use `override(...)` only on token refresh.
+- `@jwtGuard()` and `@apiKeyGuard()` work on REST endpoints; their `*HandshakeGuard()` variants work on socket controllers. Don't mix them up.
+- Never log `auth.require()` results — they may contain PII or token claims. Use a redacted view.
+- If you need a custom guard, implement `IMiddleware` (REST) or `IHandshakeMiddleware` (socket) and wire it with `@middleware(...)` / `@handshakeMiddlewares([...])`.
+
+## Testing
+
+From `@wabot-dev/framework/testing`: `RestHarness` with `jwt: true` registers a test `JwtConfig` so the real `@jwtGuard` works without env secrets (`harness.as(authInfo)` signs per-request tokens; `harness.jwt.signInvalid()` for 401 tests). `TestApiKeyRepository` is an in-RAM `ApiKeyRepository` for `@apiKeyGuard` (`register: [[ApiKeyRepository, repo]]`, `repo.addKey(authInfo)`). Harnesses also accept `authInfo` to populate the container-scoped `Auth` directly. See the `wabot-testing` skill.

package/skills/wabot-chat/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: wabot-chat
+description: Use when wiring chat input/output for a Wabot bot — receiving messages from one or more channels (cmd, socket, telegram, whatsapp, wasender), injecting a ChatBot bound to a mindset, and replying. Covers @chatController, @chatBot, @cmd / @socket / @telegram / @whatsApp / @wasender, IReceivedMessage, the ChatBot.sendMessage callback, and the @chatAdapter / runChatAdapters provider model.
+---
+
+# Chat controllers, channels, and adapters
+
+A chat controller is the entry point for messages from a transport (terminal, socket, Telegram, WhatsApp). It owns a `ChatBot` bound to one mindset and forwards the message into the bot's processing loop.
+
+## Controller shape
+
+```typescript
+import {
+  chatBot,
+  ChatBot,
+  chatController,
+  cmd,
+  socket,
+  telegram,
+  whatsApp,
+  type IReceivedMessage,
+} from '@wabot-dev/framework'
+import { PixelMindset } from './mindset/PixelMindset'
+
+@chatController()
+export class PixelChatController {
+  constructor(@chatBot(PixelMindset) private pixel: ChatBot) {}
+
+  @cmd()
+  @socket({ namespace: 'pixel' })
+  @telegram({ botToken: process.env.TELEGRAM_BOT_TOKEN! })
+  @whatsApp({ number: '+1555…', accessToken: '…', businessNumberId: '…' })
+  async onMessage(ctx: IReceivedMessage) {
+    await this.pixel.sendMessage(ctx.message, async (reply) => {
+      await ctx.reply(reply)
+    })
+  }
+}
+```
+
+Channel decorators stack: each one registers the same method on a different transport. The runner instantiates a channel per registration.
+
+`@chatController()` takes no arguments today — `IchatControllerConfig` is currently empty. It applies `@injectable()`.
+
+## `ChatBot` injection
+
+`@chatBot(MindsetCtor)` injects a `ChatBot` instance scoped to that mindset. You can have several in one controller (e.g. a "support" bot and a "sales" bot) — each gets a unique injection token under the hood.
+
+`ChatBot.sendMessage(message, callback)`:
+- Persists the incoming message as a `humanMessage` chat item.
+- Calls the mindset → adapter loop, executing any tool calls.
+- Invokes `callback(replyMessage)` once per `botMessage` item produced.
+
+Inside the loop, the bot picks `models.visionLlm` if any image is attached, otherwise `models.llm`. It will only use providers registered through `@chatAdapter` (see below).
+
+## `IReceivedMessage` and `IChatMessage`
+
+```typescript
+interface IReceivedMessage {
+  message: IChatMessage
+  reply: (message: IChatMessage) => Promise<Record<string, string> | void>
+}
+
+interface IChatMessage {
+  senderId?: string
+  senderName?: string
+  text?: string
+  images?: IChatMessageImage[]
+  documents?: IChatMessageDocument[]
+  object?: object
+  metadata?: Record<string, string>
+}
+```
+
+The `reply` callback comes from the channel — for `@cmd` it writes to stdout of the connected `cmd:channel` client; for `@socket` it emits a Socket.IO event; for `@telegram`/`@whatsApp`/`@wasender` it calls the provider's send API. You always pass an `IChatMessage` (with `text`, `images`, or `documents`); never raw strings.
+
+## Channels — what each decorator needs
+
+| Decorator | Config | Notes |
+| --- | --- | --- |
+| `@cmd()` | none | Local Unix socket terminal client. Run `npm run cmd` to chat. State stored under `.wabot/cmd-channel/<route>/`. |
+| `@socket({ namespace })` | `namespace: string \| ConfigReference<string>` | Mounts a Socket.IO namespace. Tag-fn refs (`str\`socket.namespace\``) supported. |
+| `@telegram({ botToken })` | `botToken: string \| ConfigReference<string>` | Long-poll Telegram bot. Raw token or `str\`telegram.bot_token\``. |
+| `@whatsApp(numberOrConfig)` | string OR `{ number, accessToken?, businessNumberId? }` (each may be a `ConfigReference`) | WhatsApp Cloud API. |
+| `@wasender(config?)` | `{ apiKey?, webhookSecret?, phoneNumber?, webhookPath? }` (each may be a `ConfigReference`) | WaSender integration. |
+
+Channel configs that accept `ConfigReference` resolve env vars automatically — use `str\`wasender.apiKey\`` from `@wabot-dev/framework` to point to `WASENDER_APIKEY`.
+
+## Chat resolution
+
+When a message arrives, `ChatResolver` looks up the `Chat` by `IChatConnection` (`{ chatType: 'PRIVATE' | 'GROUP', channelName, id }`). If none exists, a new `Chat` is created under a lock. You never write this resolution code — it's already wired.
+
+Inside a chat handler, these tokens are available in the child container:
+- `Chat` — the resolved chat entity
+- `ChatMemory` — append/read chat items for this chat
+- `ChatOperator` — convenience wrapper (see `wabot-mindset`)
+- `Auth` — populated if the channel attached auth (e.g. via `injectInstances`)
+
+## Chat adapters (providers)
+
+Each LLM provider has a `@chatAdapter({ provider: 'name' })` class implementing `IChatAdapter.nextItems`. The framework ships adapters for `openai`, `anthropic`, `google`, `openrouter`, `deepseek`, and `wabot`.
+
+The project runner registers adapters automatically based on env keys (`OPENAI_API_KEY` → OpenAI, etc.). To override, pass `chatAdapters: [...]` to `run({ chatAdapters: [MyAdapter, OpenaiChatAdapter] })`.
+
+To call them manually (outside the runner):
+
+```typescript
+import { runChatAdapters, OpenaiChatAdapter } from '@wabot-dev/framework'
+runChatAdapters([OpenaiChatAdapter])
+```
+
+`runChatAdapters` binds a `UnionChatAdapter` to the `ChatAdapter` token — it dispatches by `IMindsetModelRef.provider`.
+
+To build your own adapter, implement `IChatAdapter`:
+
+```typescript
+import { chatAdapter, IChatAdapter, IChatAdapterNextItemsReq, IChatAdapterNextItemsRes, singleton } from '@wabot-dev/framework'
+
+@chatAdapter({ provider: 'my-llm' })
+@singleton()
+export class MyLlmAdapter implements IChatAdapter {
+  async nextItems(req: IChatAdapterNextItemsReq): Promise<IChatAdapterNextItemsRes> {
+    // map req.systemPrompt + req.prevItems + req.tools to your API, return { nextItems, usage }
+    return { nextItems: [], usage: { inputTokens: 0, outputTokens: 0, provider: 'my-llm', model: req.models[0].model } }
+  }
+}
+```
+
+## Rules
+
+- Keep controllers thin — fetch from `ctx.message`, call `bot.sendMessage`, return. Business logic belongs in modules/services.
+- Don't pass raw strings to `ctx.reply` — wrap them in `{ text: '...' }`.
+- The reply callback is async; await it so the channel actually flushes.
+- `@chatBot(Mindset)` is a parameter decorator — it can only appear in a constructor.
+- If you add a new chat adapter, its file must be imported during the runner's scan (so the `@chatAdapter` side-effect runs); place it inside `directories`.
+- Avoid building a mindset/controller pair when one controller can route between several mindsets with multiple `@chatBot(...)` constructor params.
+
+## Testing
+
+`createChatControllerHarness({ controller })` from `@wabot-dev/framework/testing` drives a `@chatController` end-to-end without a real channel (same per-message container path as production, `@chatBot` included), with a scripted `MockChatAdapter` playing the LLM. Custom `IChatAdapter` implementations should pass `chatAdapterConformanceCases`. See the `wabot-testing` skill.