HelpfulAI ACP (agent communications)

The communications APIs HelpfulAI runs today, as Supabase Edge Functions. Each path is one function under supabase/functions/<name>/. Most answer POST with a JSON body; the public agent-calendar resources (agent-calendar-availability, -bookings, -events, -grants, -shares) use GET / POST / PATCH / DELETE, with the calendar's owner in the query string.

This spec is checked against the handlers by node scripts/check-openapi-specs.mjs (TypeScript AST, no regex): the set of paths must equal the in-scope functions (the checker's ACP_HANDLER_SCOPE in scripts/openapi/acp-scope/, not this file) that register a serve(...) handler, each operation's method must be the one the handler guards on, each x-handler.contracts schema must be the operation's request body (or a oneOf member of it), and its top-level keys, required keys, enum or union variants must equal the zod schema or action set the handler validates with. Response bodies are documented from the code and are not machine-checked yet.

Layout: this metadata root and one file per path, tag and schema area under openapi/acp/. The index is generated from those directories at build time; adding a path or schema does not edit this root. node scripts/check-openapi-specs.mjs --bundle openapi/acp.yaml prints the single-file document used by the developer portal.

Errors from _shared/errorResponse.ts are { "error": string, "code"?: string, "details"?: object }. Carrier webhooks (Telnyx, LiveKit, Resend) answer plain text on some failures.