Skip to content

AGENTS.md

Latest commit

 

History

History
98 lines (67 loc) · 4.92 KB

AGENTS.md

File metadata and controls

98 lines (67 loc) · 4.92 KB
Raw

AGENTS.md

Guidance for coding agents working in this repository. For PR workflow, signed commits, and changeset rules, see .github/CONTRIBUTING.md.

Commands

pnpm install
pnpm validate        # knip + check + typecheck + test + build — run before declaring work done
pnpm check           # lint/format (Ultracite/Biome)
pnpm fix             # auto-fix lint/format issues
pnpm typecheck
pnpm test            # all package tests via Turborepo (includes integration-tests)
pnpm test:workspace  # single Vitest run across unit-test packages only
pnpm build
pnpm dev             # watch mode
pnpm knip            # unused exports/dependencies
pnpm konsistent      # adapter/state package shape (see .github/konsistent.json)

# Per-package
pnpm --filter chat test
pnpm --filter @chat-adapter/slack build
pnpm --filter docs dev    # preview chat-sdk.dev locally

Install dependencies with pnpm add, not by editing package.json by hand.

Monorepo layout

pnpm + Turborepo monorepo. Packages are ESM ("type": "module"), TypeScript, bundled with tsup.

Path Role
packages/chat Core SDK (chat): Chat, types, mdast markdown, chat/adapters catalog
packages/adapter-* Platform adapters (slack, teams, gchat, discord, telegram, whatsapp, github, linear, web, messenger, twilio, …)
packages/adapter-shared Shared adapter utilities
packages/state-* State adapters (memory, redis, ioredis, pg)
packages/create-chat-sdk create-chat-sdk CLI scaffold
packages/tests @chat-adapter/tests — Vitest factories/matchers for adapter tests
packages/integration-tests Replay + emulator tests; needs credentials for live API tests
apps/docs fumadocs site (chat-sdk.dev)
examples/* Example bots; package.json name must be example-* (private, no changeset)

When editing a specific package, read its AGENTS.md if present (most adapters, state packages, create-chat-sdk, and packages/chat/src/adapters/ have one).

Architecture

Core concepts

  1. Chat (packages/chat/src/chat.ts) — coordinates adapters and handlers.
  2. Adapter — webhook verification, parsing, and a FormatConverter for markdown ↔ platform format.
  3. StateAdapter — subscriptions, distributed locks, key/value cache, lists, queues.
  4. Thread — conversation handle: post(), subscribe(), startTyping(), setState(), etc.
  5. Message — normalized message: text, formatted (mdast AST), raw (platform-specific).

Thread IDs

{adapter}:{channel}:{thread} — e.g. slack:C123ABC:1234567890.123456. Some adapters base64-encode IDs that contain delimiters (Teams, Google Chat).

Webhook flow

  1. Platform → /api/webhooks/{platform}
  2. Adapter verifies and parses; calls chat.handleIncomingMessage()
  3. Chat acquires a thread lock, then routes to onSubscribedMessage, onNewMention, or onNewMessage
  4. Handler receives Thread and Message

Formatting

mdast is the canonical message format. Each adapter's FormatConverter implements toAst, fromAst, and renderPostable.

Adapter catalog

packages/chat/src/adapters/index.ts powers the zero-dependency chat/adapters subpath. See packages/chat/src/adapters/AGENTS.md when adding or changing catalog entries — keep it in sync with apps/docs/adapters.json.

Working on adapters and state packages

  • Run pnpm konsistent after changing public exports; conventions are documented in .github/CONTRIBUTING.md.
  • sample-messages.md in adapter packages holds real webhook payloads — extend it when fixing parsers or adding event support.
  • Adapter factory/config naming: create${Name}Adapter, ${Name}Adapter, ${Name}AdapterConfig (see konsistent config for gchat → GoogleChat etc.).

Testing

packages/chat/src/mock-adapter.ts:

  • createMockAdapter(name), createMockState(), createTestMessage(), mockLogger

For production-traffic replay tests, see packages/integration-tests/fixtures/replay/README.md. Recordings export via pnpm recording:list / pnpm recording:export <session-id> from examples/nextjs-chat.

Docs and releases

  • User-facing docs: apps/docs/content/ → chat-sdk.dev/docs. Update relevant pages when behavior, public APIs, or env vars change.
  • Behavioral package changes need a changeset (pnpm changeset). Docs-only, tests-only, CI, and examples/* changes do not.

Code style

Ultracite (Biome) via pnpm check / pnpm fix. Most issues auto-fix.

Beyond Biome: prefer unknown over any; top-level regex literals; for...of over .forEach; always await returned promises; no console.log / debugger in shipped code; throw descriptive Error objects. React (docs/examples): function components, stable keys, semantic HTML/ARIA.