release: prepare v1.5.0 — client version bumps, changelogs, beta docs

[jiashuoz]

Summary

Release-prep for the additive v1.5.0 product release (contacts/outreach beta, scheduled sending beta, webhook delivery observability, thread identity beta, MIME/DKIM hardening). Version bumps + changelogs + agent-guidance and public-doc updates only — no code changes. (No API surface changes, so the client-surface checklist is omitted.)

Update (per Josh's direction): the core /v1 surface is now presented as stable/GA with the beta set explicitly enumerated, grounded in the spec's machine-readable x-stability-level markers. Verified against api/openapi.yaml in this tree: 43 GA operations, 29 beta operations (note: the templates+starter-templates beta group is 8 ops, not 9 — the 29 total holds). Changes in the second commit (1eeb187c):

• docs/api.md — new prominent "Stability: GA and beta surface" section near the top: GA/beta matrix by resource group, the beta-fields-on-GA-operations list (scheduled sending, thread_id, template refs, managed unsubscribe, review-hold projections, export interior schemas), and the beta events, cross-referencing x-stability-level as the source of truth and the existing "Beta operations" table.
• README.md — the stale "release candidates / GA planned by July 31, 2026" banner replaced with the GA statement + enumerated beta list, linking the matrix.
• AGENTS.md — the same one-sentence release-candidate claim fixed (it would otherwise keep telling agents the API is unstable).
• Changelogs (TS 5.5.0 / Py 5.5.0 / CLI 2.2.0) — one-line pointer to the stability matrix.
• cli/README.md — e2a contacts marked beta (MCP README already was).

Version bumps

Package	From	To	Where
@e2a/sdk (TS)	5.4.0	5.5.0	sdks/typescript/package.json
e2a (PyPI)	5.4.0	5.5.0	sdks/python/pyproject.toml
@e2a/cli	2.1.0	2.2.0	cli/package.json
e2a plugin	0.5.0	0.6.0	.claude-plugin/.codex-plugin/.cursor-plugin plugin.json + .claude-plugin/.cursor-plugin marketplace.json

Root package-lock.json refreshed (workspace version entries only). The Internal SDK version sync gate has no separate fixture file — scripts/check-sdk-version-sync.mjs reads the live package.jsons; cli/mcp declare @e2a/sdk@^5.0.0, satisfied by 5.5.0 (verified green). @e2a/mcp-server stays frozen at 0.5.0 (npm publish retired — the 0.5.0 there is unrelated to the plugin's old 0.5.0).

Deliberately NOT bumped: tests/sdk-monitor pins the exact published @e2a/sdk@5.4.0 / @e2a/cli@2.1.0 / e2a==5.4.0. Main's monitor image build installs from the public registries and would fail on unpublished versions — the monitor pins are updated in a follow-up only after the packages are visible on npm/PyPI (release-order step 4 below).

Changelog highlights (TS 5.5.0 / Py 5.5.0 / CLI 2.2.0)

• Contacts & outreach (beta) — account contacts CRUD, bulk import (≤1,000 rows, per-row outcomes, idempotent replay) and safe reversal (only verifiably untouched batch rows are removed), per-agent outreach state with server-derived reply/delivery facts and duplicate-send-safe due queries, contact.due event.
• Scheduled sending (beta) — send_at on send/reply/forward, up to 90 days ahead; status=scheduled + scheduled_at are durable acceptance; cancel via trash-before-submission, restore-before-scheduled_at re-arms; review holds drop the schedule.
• CLI — e2a contacts command tree (incl. CSV import with --dry-run) and --send-at on send/reply.
• Beta thread_id on message reads (PR feat(threading): materialize mailbox-local email thread identity #765) — server-owned mailbox-local topology identity, response-only.

Guidance & docs

• plugins/e2a/skills/e2a/SKILL.md (skill v23 → v24; skill integer version and plugin semver remain distinct concepts): status=scheduled is durable success — never retry; scheduled_at is the future submission time; wait=sent does not wait for a future send_at; send_at (scheduled sending) vs next_action_at/contact.due (outreach scheduling) explicitly contrasted.
• docs/api.md: new Contacts & Outreach (beta) resource section — all 11 operations, account-vs-agent scope split, pagination/filters, ETag/If-Match, metadata bounds (flat, ≤50 keys, ≤128 B keys, ≤4 KiB values, ≤16 KiB total) and import bounds, idempotency, import-reversal retention rule matched to internal/identity/contacts.go (DeleteImportBatch: untouched-only deletion — updated_at == created_at, no wire activity, no message history, no surviving engagement; provenance tags never move on merge re-import), derived vs caller-owned engagement fields, contact.due behavior. This also fulfills the OpenAPI metadata field's "see the field bounds in the API docs" pointer.
• docs/events.md: contact.due corrected — it is a notification, not an execution mechanism; only a deployed webhook receiver (or events-log poller) can use it to wake an agent runtime; it does not start an MCP/WebSocket/Claude Code/Codex session.
• README.md: contacts/outreach and scheduled sending added to the feature list, both marked beta.

Required release order

1. Merge this PR.
2. Publish the SDKs: tag ts-sdk-v5.5.0 and python-v5.5.0.
3. Cut the product v1.5.0 tag — builds server/web/MCP images and publishes the CLI (CLI publish requires the cli/package.json bump in this PR; npm rejects republish otherwise).
4. After the packages are visible on npm/PyPI, bump and verify the tests/sdk-monitor pins in a follow-up PR.
5. Run the staging release pipeline gates (staging deploy → prober → conformance) against 1.5.0.
6. Only then the e2a-ops promotion PR (release.env bump).

Test evidence (all local/offline)

• node scripts/check-sdk-version-sync.mjs — green (cli + mcp in sync with workspace SDK 5.5.0)
• node scripts/validate-plugin.mjs — green (4 skills, version 0.6.0, manifests in sync across Claude/Codex/Cursor)
• node --test scripts/plugin-agent-guidance.test.mjs — 9/9 pass
• bash scripts/check-repository-text-integrity.sh — green (incl. agent-doc mirrors + SDK example contracts)
• npm run build && npm test --workspace @e2a/sdk — 228/228 pass + type tests
• npm run build && npm test --workspace @e2a/cli — 266/266 pass
• npm run build && npm test --workspace @e2a/mcp-server — 291/291 pass + type tests
• Python SDK: pytest tests/ (excl. live contract) — 498 pass / 13 skip, coverage 94%; mypy — clean
• No Go/handler/spec changes, so the spec, generated-code, and compat gates are untouched by construction; GitHub-anchor links in the new docs verified against GitHub's slug algorithm.

Open questions for Josh

1. GA-language contradiction: Resolved by Josh's direction — the core /v1 surface is stable/GA with the beta set explicitly enumerated; README and AGENTS.md now say so and docs/api.md's stable-contract stance stands (see the stability-matrix update above).
2. The contact.due payload is still untyped (internal/contactdue, no EventEnvelope data schema) while every other stable event has one — fine for beta, but worth a typed schema before it's declared stable.

Review fixes (applied at 08ed71ba)

Five validated fixes from the pre-merge review pass, one commit each:

1. a7cdfeef — regenerate stale Python uv.lock. The 5.5.0 version bump touched pyproject.toml but not the lock, so uv lock --check failed at the previous head (contributors/CI on uv sync --locked would break at the release tag). Regenerated; the only change is the editable e2a package 5.4.0 → 5.5.0, no third-party pin churn. uv lock --check now passes.
2. c8e59d56 — untrack sdks/python/.coverage and keep it out of the sdist. A 53 KB pytest-cov SQLite DB with absolute local paths, tracked since v1.3.0 and shipping in the sdist (hatchling default selection). Untracked, gitignored (sdks/python/.coverage*), plus a defensive [tool.hatch.build.targets.sdist] exclude — uv build --sdist verified clean. (Same untracking is also in flight on the fix(api): input validation and error mapping #780 branch; the two converge at merge.) No packaging/artifact-content test exists in the repo to extend — noted rather than inventing one.
3. de55f072 — GA baseline reconciled to the 1.5.0 freeze. docs/api.md no longer says "stable … as of e2a 1.0" (now names 1.5.0 and repeats the not-a-baseline caveat for v1.0.x tags) and the "Once /v1 is GA … (Pre-GA, the API is still being frozen …)" deprecation bullet is present-tense with the endpoint removal as history. SECURITY.md's "has not yet published its official GA release" supported-versions story updated to match. Historical uses of "pre-GA" (changelogs, design docs, code comments, docs/api-compatibility-gate.md's freeze-anchor mechanics) deliberately left as history.
4. 12ee043f — beta inventory completed, both markers named. The summary list of beta-fields-on-GA-operations now includes the property-level lifecycle_transitions marker on the seven event payload schemas; README (and the api.md list header) now document x-experimental-values alongside x-stability-level; and the older compatibility-rules beta enumeration (which had drifted — no contacts, lifecycle diagnostics, or thread_id) is collapsed into a pointer at the stability matrix, leaving one source of truth. Inventory re-derived from the spec: 29 op-level, 63 schema-level, 30 property-level x-stability-level markers + 6 x-experimental-values sites — all accounted for in the matrix.
5. 08ed71ba — CLI npm tarball no longer ships compiled tests. dist/__tests__/*.test.js was 17 of 36 packed files. cli/tsconfig.json now excludes src/__tests__; a new cli/tsconfig.test.json + typecheck script (mirroring sdks/typescript) keeps tests typechecked via npm test. npm pack --dry-run: 19 files, all runtime dist output; CLI suite still 266/266.

Verification at 08ed71ba: make spec-check green (no spec changes), scripts/check-repository-text-integrity.sh green, node scripts/validate-plugin.mjs green, node --test scripts/sync-agent-docs.test.mjs 4/4, TS SDK + CLI builds green.

🤖 Generated with Claude Code

[jiashuoz]

Team review at exact head 1eeb187 found four release-blocking documentation/package issues plus one packaging cleanup:

1. [P2] Regenerate the Python lockfile. sdks/python/pyproject.toml is 5.5.0, but sdks/python/uv.lock still records the editable e2a package as 5.4.0. On this exact head, uv lock --check reports that the lockfile needs updating, so locked contributor/CI environments are no longer reproducible. Please update uv.lock and consider checking it in CI.

2. [P2] Remove sdks/python/.coverage from the source distribution. This tracked SQLite coverage database is included by the current Hatch sdist configuration and exposes absolute local development/worktree paths. The wheel is clean, but the sdist is not. Please remove and ignore the artifact, exclude it defensively from sdists, and add an artifact-content assertion.

3. [P2] Resolve the GA baseline contradiction. README.md now says v1.0.x predates the freeze and is not a compatibility baseline, while docs/api.md says the stable surface is stable as of e2a 1.0 and later still says /v1 is not yet GA. Pick the real baseline (apparently 1.5.0), state it consistently, and convert the remaining pre-GA language to present tense.

4. [P2] Complete the promised exhaustive beta inventory. lifecycle_transitions is beta on seven otherwise-GA event payload schemas, but the new top-level matrix and README omit it. The README also says beta is identified by x-stability-level, while beta enum/status values use x-experimental-values (including scheduled, beta event-type values, and blocked_by_policy). The older compatibility inventory is missing additional surfaces such as contacts/outreach, lifecycle, and thread_id. Please consolidate this into one complete source of truth and document both extension mechanisms.

5. [P3] Exclude compiled CLI tests from the npm package. npm pack --dry-run includes dist/tests/*.test.js because the production build compiles all of src and the package publishes dist. A production tsconfig or explicit package allowlist would avoid shipping test code.

Verification on the exact head: the OpenAPI operation counts are internally consistent (72 total: 43 GA, 29 beta), the detailed beta operation table matches all 29 beta operations, SDK version sync/plugin validation/repository text-integrity checks pass, TS and CLI builds pass, and GitHub CI is green. These findings are therefore release-preparation gaps rather than failures of the new operation-count inventory.