Agent instructions (developers)

AGENTS.md and CLAUDE.md are intentionally the same. Edit both when you change this document so Cursor and Claude Code stay aligned.

What this repo is

Node.js + TypeScript backend for real phone calls → OpenAI Realtime (voice).
Two integrations: Twilio (src/service/twilio-phone/) and Amazon Connect + OpenAI SIP (src/service/amazon-connect-phone/openai-sip-webhook/).
Phone-only — no browser voice UI in this kit.

Area	Role
`src/foundation/`	Shared OpenAI helpers, Twilio WebSocket, MCP servers, Amazon Connect SDK helpers.
`src/service/twilio-phone/`	Twilio HTTP + wiring into foundation.
`src/service/amazon-connect-phone/`	Connect: incoming webhook, accept/hangup, Realtime WS, tools, SIP instructions.
`doc/`	Architecture and integration guides — read before large changes.

Imports use @/* → src/*; build uses tsc-alias for dist/.

Small, focused diffs — match existing style; don’t refactor unrelated code.
Lint / format — ESLint uses Airbnb (eslint-config-airbnb-base + @kesills/eslint-config-airbnb-typescript) with Prettier (eslint-config-prettier). Run npm run lint and npm run format before you finish.
Tools — New Realtime tools: Zod schema + matching parametersJsonSchema, register in openai-sip-webhook/tools/index.ts (same pattern as existing tools).
Voice prompts — Connect SIP: openai-sip-webhook/agents/ (e.g. sip-instructions.ts, entry-agent.ts). Twilio: service/twilio-phone/agents/realtime-phone/.

Never commit secrets — .env is gitignored; use .env.example for keys names only.
Don’t log API keys, tokens, or full PII; sanitize error messages aimed at end users.

npm install
npm run dev      # nodemon
npm run build && npm run start
npm run lint
npm run format

Booking/post-booking MCP and trip-intake examples are illustrative — replace with your own product logic and compliance rules.