Changelog

Version history and release notes for the autoplay-sdk Python package.

The canonical changelog for releases and PyPI sdists also lives in the repository as CHANGELOG.md. This page mirrors that file for the documentation site, with links pointed at these docs.

---

[0.11.0] — 2026-07-02

Changed

• onboard_product / onboard_product_sync now register against the AWS activity connector. DEFAULT_CONNECTOR_URL is https://connector.autoplay.ai (was the legacy Render connector). The POST /products request body now carries provider + optional ingest_secret + force (replacing webhook_secret / integration_type=event_stream / force_reregister), and the response is read from credentials.{ingest_secret, mcp_key} + setup.{ingest_url, ingest_auth, mcp_url, mcp_auth}.
• OnboardProductResult reshaped to the AWS model: product_id, provider, ingest_url, ingest_secret, ingest_auth, mcp_url, mcp_key, mcp_auth, connector_response.

Added

• build_aws_register_payload and post_aws_register_product in autoplay_sdk.admin.connector_registration_http.

Removed

• Render/SSE-shaped fields from OnboardProductResult: webhook_url, stream_url, webhook_secret, unkey_key, unkey_key_id, integration_type, render_sync_performed.
• onboard_product keyword args webhook_secret and force_reregister (replaced by ingest_secret and force); user_activity_provider is now required.

Breaking changes

onboard_product targets a different connector with a different request/response contract. Existing Render customers are unaffected — they stay on their pinned SDK version and the legacy connector; only new onboarding is routed to AWS. If you call onboard_product, use result.ingest_url + result.ingest_secret to configure your provider’s webhook, and result.mcp_url + result.mcp_key for the agent’s MCP read, instead of the old webhook_url / stream_url / unkey_key. The legacy Render onboarding flow remains available in autoplay_sdk.admin.product_onboarding / autoplay_sdk.admin.onboard for internal Render tooling.

---

[0.10.0] — 2026-06-21

Added

• autoplay_sdk.storage — a new, self-contained subsystem for cross-session persistence of UserAdoptionState plus frozen per-session snapshots, behind a pluggable adapter interface.
  • AutoplayStorageAdapter — a @runtime_checkable Protocol (mirrors BufferBackend) with async save_user_state / get_user_state / save_session_snapshot / get_session_snapshot. The wire boundary is plain JSON dicts, so custom adapters stay decoupled from the SDK’s model classes.
  • StorageManager — fans writes out to every adapter (one failing sink never blocks the others) and reads from the first adapter that returns a value (list the readable primary first).
  • RedisStorageAdapter(redis_url=...) — primary read+write adapter; owns a lazy redis.asyncio pool with graceful degradation (mirrors RedisSessionStateStore), SET NX write-once for snapshots. Needs the redis extra.
  • InMemoryStorageAdapter — tests/dev adapter with write-once snapshot semantics.
  • Product-scoped key builders — user_state_key(product_id, user_id) and session_key(product_id, user_id, session_id).
  • Session lifecycle helpers — init_user_state, on_session_start, on_session_end, build_agent_context. on_session_end resolves the onboarding summary via an injected summarizer callable or a pre-computed summary= — the SDK never calls an LLM.
• Write-only analytics sinks — AmplitudeStorageAdapter / PostHogStorageAdapter (deep-import from autoplay_sdk.storage.adapters.{amplitude,posthog}), gated behind a new autoplay-sdk[analytics] extra. They save_* (with optional property_prefix=) and return None from get_*; failures are best-effort (logged, never raised).
• SessionSnapshot — a new frozen, write-once per-session model with to_dict / from_dict (defensive) and a SessionSnapshot.from_adoption_state(...) helper that builds the snapshot from a live UserAdoptionState (reusing the model’s derived helpers — no hand-rolled mapping).
• SessionIndexEntry + a bounded sessions index on UserAdoptionState — sessions_count (monotonic lifetime total), current_session_id, and sessions_index (capped to the most recent 50 via record_session), plus set_current_session.
• OnboardingState.summary and OnboardingState.completion_rate — cross-session briefing + cached completion snapshot.
• ONBOARDING_SUMMARY_PROMPT (v0.1, plain-text output) in autoplay_sdk.prompts and a pure build_onboarding_summary_input(snapshot) builder in autoplay_sdk.user_adoption_state.
• Exports — storage symbols re-exported from top-level autoplay_sdk; SessionSnapshot, SessionIndexEntry, COMPLETION_RATE_DENOMINATOR_*, and build_onboarding_summary_input from autoplay_sdk.user_adoption_state. Sink adapters stay deep-import only.
• autoplay_sdk.observability — a pluggable error-reporter seam (set_error_reporter / report_error) so a host application can forward SDK-internal failures to its own sink (Slack, Bugsnag, logs, …). The SDK calls report_error at its swallow points — RAG embed/upsert, Redis state/snapshot writes, and event-buffer overflow drops — so those otherwise-silent failures become observable. Best-effort and a no-op until a reporter is registered; reporting never raises into SDK logic.

Documentation

• New page State storage & session capture covering the three-step integration flow, the adapter/manager model, Redis key schema, write-only sinks, and the injected-summarizer pattern.
• User adoption state persistence note updated to point at the new storage adapters.

Breaking changes

None — purely additive. The new UserAdoptionState fields (sessions, onboarding.summary, onboarding.completion_rate) read with safe defaults, so existing snapshots load unchanged and the _v snapshot version is unchanged.

---

[0.9.2] — 2026-06-21

Added

• Onboarding workflow steps — each OnboardingWorkflow can now declare an ordered list of **WorkflowStep**s (step_id, name, description, required), configured per product under integration_config.onboarding_workflows[].steps. Steps are context/signal for the LLM (what “done” looks like) and for explainability — they are not a checklist gate. required is a hint, not a hard gate. Helper OnboardingWorkflow.required_step_ids.
• StepProgress — the agent’s per-step belief (step_id, status reusing WorkflowStatus, confidence, evidence, completed_at, last_evaluated_at), a deliberate parallel to WorkflowProgress one level down.
• WorkflowProgress.steps — a dict[str, StepProgress] map of per-step beliefs, with a completed_step_ids helper and an upsert_step_progress(step_id, *, status, confidence, evidence="", now=None) mutation (write-once completed_at, mirroring upsert_workflow_progress).
• is_plan_complete(plan, workflow_progress) — thin convenience wrapper over split_workflows (True when no outstanding workflows; an empty plan is never complete). Completion stays the LLM’s call via WorkflowProgress.status — steps never gate it.
• step_completion_ratio(workflow, wp) — fraction of a workflow’s declared steps the LLM believes are completed. For display/telemetry only; never used to decide completion.
• Exports — WorkflowStep, StepProgress, is_plan_complete, step_completion_ratio added to autoplay_sdk.user_adoption_state.

Documentation

• User adoption state updated with the steps data model, the product-config steps schema, and the completion semantics (LLM-authoritative; steps are signal, not a gate).

Breaking changes

None — purely additive. steps is read with safe defaults, so existing snapshots (no steps key) load unchanged and the _v snapshot version is unchanged.

---

[0.9.1] — 2026-06-16

Added

• Amplitude activity provider support — adds the SDK provider wiring and activity skill needed to configure Amplitude as an event source.

Documentation

• Expanded the setup and quickstart docs for activity providers, agent skills, MCP server setup, and Intercom tutorial assets.

---

[0.9.0] — 2026-06-12

Added

• PostHogProvider.create_destination() + .verify() — deterministic, idempotent creation (and verification) of the PostHog → Autoplay “Autoplay Event Stream” hog_function destination, built on the provider abstraction. Powers the one-command autoplay-setup onboarding flow (plumbing runs as tested code, not via an agent).

Changed

• activity-posthog skill is now the single source (modular: SKILL.md + references/ + examples/), replacing the forked posthog-setup skill the setup bundle used to ship. Scoped to frontend code only (the CLI now owns destination create/verify and the end-to-end event check). Identify uses the app’s stable user id on login (never the anonymous id) + reset() on logout.

---

[0.8.0] — 2026-06-09

Added

• autoplay_sdk.user_adoption_state — a new per-user adoption-state module, orthogonal to the per-session SessionState FSM and keyed by user_id. Tracks where a user is in their product lifecycle and how proficient they are, decided by an LLM judge and fed back into chat / proactive prompts.
• Enums — JourneyState (onboarding / onboarded), MasteryLevel (novice → beginner → intermediate → proficient → power_user), and WorkflowStatus (not_started / in_progress / completed).
• UserAdoptionState — top-level per-user record: a fully dynamic, schema-less metadata bag (with a role convenience property), journey_state, mastery, discovered_features, and an onboarding sub-object. Mandatory non-empty user_id (raises otherwise, like SessionState); to_dict() / from_dict() with _v snapshot versioning and defensive enum coercion; transition helpers (set_journey_state, set_mastery, record_discovered_features, mark_welcomed, mark_judged) that log structured events; and to_prompt_block() for compact prompt injection.
• Mastery (0-10 rating, clamped, + MasteryLevel + reason), WorkflowProgress (per-flow status / confidence / evidence / timestamps — the agent’s evolving belief from the live activity stream), StepInAssessment (latest “should I step in?” decision + timing rationale), and OnboardingState (welcome lifecycle, workflow_progress map, derived completed / in_progress / outstanding helpers, upsert_workflow_progress, record_step_in).
• ExplorationGateConfig + evaluate_hard_gate() — pure, side-effect-free “let the user explore first” floor (role allowlist, min time on app, min distinct features, welcome cooldown, nudge cap). Returns (passed, reason); the LLM owns timing on top of the floor.
• OnboardingWorkflow / OnboardingPlan (parsed from config, role-filterable via for_role) + pure split_workflows() → (completed, in_progress, outstanding).
• Query → tour matching primitive — build_tour_match_input() and parse_tour_match_output() (validates ids against a role-filtered catalog, safe fallback on malformed JSON), plus TourCatalogEntry and TourMatchResult.
• Versioned prompts in autoplay_sdk.prompts (each a dict with name / description / version / content, JSON-object output): ADOPTION_STATE_JUDGE_PROMPT, TOUR_MATCH_PROMPT, ONBOARDING_WELCOME_PROMPT (all v0.1).
• Top-level exports from autoplay_sdk: user_adoption_state, UserAdoptionState, JourneyState, MasteryLevel, WorkflowStatus.

Documentation

• New User adoption state reference page covering the two axes (journey vs mastery), the full state model, the explore-first gate, onboarding plans, and the query → tour matcher. The SDK ships pure logic + prompt definitions only; persistence and acall_llm runners are integration-owned.

Breaking changes

None — the module and exports are purely additive.

---

[0.7.9] — 2026-05-25

Breaking changes

• SessionState.session_id is now a required field — no default. SessionState() raises TypeError. Use SessionState(session_id="...") or InMemorySessionStateStore.get_or_create(session_id). from_dict() still handles old snapshots gracefully via .get("session_id", "").

Added

• SessionState.can_deliver_proactive() -> tuple[bool, str] — canonical FSM gate check. Returns (True, "ok") when the session is THINKING with no active cooldown; (False, reason) otherwise. Callers must call tick() before this method. Replaces any inline current_state == THINKING and not thinking.cooldown_active pattern.
• SessionState now holds session_id: str (the only mandatory scope key) and metadata: dict[str, Any] (open bag for optional identity context — user_id, email, any future fields). Both fields are persisted via to_dict() / from_dict() and default to empty for backward compatibility.
• RedisSessionStateStore — Redis-backed SessionState store for production use. Key pattern autoplay:session_state:{session_id}, configurable TTL (default 24 h), graceful fallback on Redis errors. Requires pip install "autoplay-sdk[redis]".
• AutoplayChatbotManager — high-level wrapper that handles all session lifecycle automatically. Developers implement only _post_note and call two methods: on_actions(payload) from the Autoplay stream and on_chatbot_event(session_id, conversation_id) from the chatbot webhook.
• AutoplayChatbotManager(session_store=...) — optional parameter to inject a custom store. Defaults to InMemorySessionStateStore(). Pass RedisSessionStateStore(redis_url=...) for production.
• AutoplayChatbotManager.save_state(state) — public method for persisting state after external FSM transitions (transition_to_proactive, transition_to_reactive, tick, start_cooldown, interaction recorders). on_actions and on_chatbot_event call this automatically; use save_state only for mutations that happen outside those entry points.
• InMemorySessionStateStore — canonical store for SessionState objects. get_or_create(session_id) is the first call in every handler. async interface for drop-in Redis-backed replacement.
• BaseChatbotWriter.__init_subclass__ enforcement — raises TypeError at class-definition time (module import) when a subclass sets SESSION_LINK_WEBHOOK_TOPICS without overriding _parse_session_link_webhook_payload. Converts a silent production crash into a startup error caught by tests and local runs. Subclasses that leave SESSION_LINK_WEBHOOK_TOPICS = () are unaffected.
• link_conversation now auto-detects ConversationEventType.NEW vs REPLY_EXISTING from the store when event is not passed — removes the last manual determination from integration authors.
• link_conversation now infers session_id from state.session_id when not passed explicitly. Existing callers that pass session_id are unaffected.
• link_conversation raises ValueError if session_id is empty after resolution, with a clear message pointing to InMemorySessionStateStore.get_or_create.
• AutoplayChatbotManager and InMemorySessionStateStore exported from top-level autoplay_sdk.
• AutoplayChatbotManager.on_chatbot_event now persists the updated SessionState back to RedisSessionStateStore after linking so the conversation link survives restarts.
• redis optional extra added to pyproject.toml: pip install "autoplay-sdk[redis]".

Changed

• ConversationEvent renamed to ConversationEventType — the old name was misleading because it read as a data container rather than a type discriminator. A deprecated backward-compat alias ConversationEvent = ConversationEventType is exported from both autoplay_sdk and autoplay_sdk.chat; it will be removed in the next major version. Update any import of ConversationEvent to ConversationEventType.
• proactive_fsm_gate_for_session delivery invariant clarified — no linked conversation → first proactive → always allowed (a new conversation will be created and linked). A linked conversation → check FSM via can_deliver_proactive(). The fallback_conversation_id parameter has been removed.
• Polling gates use session.can_deliver_proactive() directly — polling paths (context_payload.py, routes.py) load and tick the session for the known conversation_id, then call can_deliver_proactive() on the already-loaded session. They no longer go through proactive_fsm_gate_for_session (which has delivery-specific semantics).
• AutoplayChatbotManager.on_chatbot_event removes the isinstance(store, RedisSessionStateStore) guard — save is always called regardless of which store is wired. on_actions does not save (no state mutation occurs during action delivery; first-creation is already persisted by get_or_create).
• InMemorySessionStateStore gains a no-op save(state) method so all call sites are uniform.

Documentation

• BaseChatbotWriter: rewritten to lead with AutoplayChatbotManager as the recommended path, updated session-first linking section to show InMemorySessionStateStore + get_or_create pattern, added Production persistence section with RedisSessionStateStore one-line swap.
• autoplay-core skill: added Integration Self-Reasoning Checklist — 5 categories agents must reason through before an integration is complete: session identity, race conditions, chatbot linking, proactive triggers, and production persistence. Section 4 updated to use can_deliver_proactive() as the canonical gate check and fixes a stale method reference (to_proactive → transition_to_proactive). Added Universal Scoping Pattern — the canonical 4-step flow (scope → parse webhook → link → deliver) that applies identically to every chatbot integration.
• SessionState class docstring now lists conversation_linked and conversation_id in its Fields section.
• Agent session states Key Methods table now includes can_deliver_proactive(); ThinkingState table now includes active_cooldown_period_s.

---

[0.7.8] — 2026-05-21

Changed

• Bumped package version to 0.7.8.

---

[0.7.7] — 2026-05-21

Changed

• Bumped package version to 0.7.7.
• Fixed circular import between autoplay_sdk.integrations.intercom and autoplay_sdk.proactive.triggers by moving proactive_trigger_canonical_url_ping_pong and proactive_trigger_canonical_url_ping_pong_projects_either_leg into autoplay_sdk.proactive.triggers._url_predicates. intercom.py re-exports both for backward compatibility.

---

[0.7.6] — 2026-05-18

Fixed

• autoplay_sdk/skills/autoplay-migrate-imports/SKILL.md — tightened the discovery rg filter to require a word boundary ((\.|\s)) after the canonical-domain alternation group. Without it, deprecated sub-modules whose names start with a canonical prefix (context_store, proactive_triggers, agent_state_v2, rag_query) were silently excluded from results, leaving 4 of 6 legacy imports unflagged.

Changed

• autoplay_sdk/skills/autoplay-migrate-imports/SKILL.md — inlined the full legacy→canonical path mapping table directly in the skill file. The previous wording (“see the changelog mapping table”) referenced a doc that does not ship inside the wheel, so agents had no static replacement guidance and had to rely on runtime DeprecationWarning messages to discover new paths.

Documentation

• Updated BaseChatbotWriter with a new session-first linking section covering:
  • ConversationEventType.NEW vs ConversationEventType.REPLY_EXISTING
  • canonical dual-write flow via link_conversation(...) (ConversationLinkStore write, then SessionState.on_conversation_linked(...))
  • hot-path routing with resolve_linked_conversation_id(state) from session-owned state.
• Expanded Agent session states v2 docs with:
  • explicit SessionState link fields (conversation_linked, conversation_id)
  • on_conversation_linked(link) overwrite/no-op semantics and invariants
  • a state/flag matrix for THINKING, PROACTIVE, and REACTIVE.
• Added cross-SDK data-structure mapping in Typed payloads and Payload schema, clarifying boundaries between session state, link state, webhook parse models, and stream payloads.

---

[0.7.5] — 2026-05-17

Changed

• Bumped package version to 0.7.5.
• Expanded the test optional dependency extra to include async/runtime test dependencies (pytest-asyncio, fakeredis, respx) so pip install -e ".[serve,test]" is enough for SDK CI and local test runs.
• Enabled asyncio_mode = "auto" in pytest config so async tests are discovered consistently without requiring explicit per-test markers.

---

[0.7.4] — 2026-05-16

Summary

Domain-oriented internal reorganization with one-release compatibility shims. Old import paths still work in 0.7.4 and emit DeprecationWarning; they are removed in 1.0.0.

Added

• autoplay_sdk.compat shim registry and helper.
• tests/compat/test_import_compat.py import parity tests.
• CI workflow for import compatibility across Python 3.10/3.11/3.12.
• Migration skill: autoplay-migrate-imports.

Changed

• Canonical import domains now use core, chat, context, proactive, agent_state, api, rag.
• autoplay-install-skills now supports --migrate.

Deprecated paths (remove in 1.0.0)

autoplay_sdk.rag remains a stable alias in 0.7.4 (no deprecation warning).

Old	New
autoplay_sdk.serve	autoplay_sdk.api
autoplay_sdk.serve.fastapi	autoplay_sdk.api.fastapi
autoplay_sdk.agent_states	autoplay_sdk.agent_state.v1.states
autoplay_sdk.agent_states.state_machine	autoplay_sdk.agent_state.v1.state_machine
autoplay_sdk.agent_states.types	autoplay_sdk.agent_state.v1.types
autoplay_sdk.agent_states.proactive_idle_expiry	autoplay_sdk.proactive.state.idle_expiry
autoplay_sdk.agent_state_v2	autoplay_sdk.agent_state.v2.states
autoplay_sdk.agent_state_v2.session_state	autoplay_sdk.agent_state.v2.session_state
autoplay_sdk.agent_state_v2.types	autoplay_sdk.agent_state.v2.types
autoplay_sdk.rag_query	autoplay_sdk.rag.query
autoplay_sdk.rag_query.assembly	autoplay_sdk.rag.query.assembly
autoplay_sdk.rag_query.formatters	autoplay_sdk.rag.query.formatters
autoplay_sdk.rag_query.pipeline	autoplay_sdk.rag.query.pipeline
autoplay_sdk.rag_query.watermark	autoplay_sdk.rag.query.watermark
autoplay_sdk.proactive_resilience	autoplay_sdk.proactive.resilience.resilience
autoplay_sdk.proactive_resilience.circuit	autoplay_sdk.proactive.resilience.circuit
autoplay_sdk.proactive_resilience.config	autoplay_sdk.proactive.resilience.config
autoplay_sdk.proactive_resilience.keys	autoplay_sdk.proactive.resilience.keys
autoplay_sdk.proactive_resilience.outcomes	autoplay_sdk.proactive.resilience.outcomes
autoplay_sdk.proactive_resilience.protocol	autoplay_sdk.proactive.resilience.protocol
autoplay_sdk.chatbot	autoplay_sdk.chat.chatbot
autoplay_sdk.chat_pipeline	autoplay_sdk.chat.chat_pipeline
autoplay_sdk.context_store	autoplay_sdk.context.context_store
autoplay_sdk.agent_context	autoplay_sdk.context.agent_context
autoplay_sdk.user_index	autoplay_sdk.context.user_index
autoplay_sdk.summarizer	autoplay_sdk.context.summarizer
autoplay_sdk.models	autoplay_sdk.core.models
autoplay_sdk.exceptions	autoplay_sdk.core.exceptions
autoplay_sdk.metrics	autoplay_sdk.core.metrics
autoplay_sdk.onboarding	autoplay_sdk.admin.onboarding
autoplay_sdk.proactive_idle_expiry	autoplay_sdk.proactive.state.idle_expiry
autoplay_sdk.proactive_triggers	autoplay_sdk.proactive.triggers
autoplay_sdk.proactive_triggers.builtin_catalog	autoplay_sdk.proactive.triggers.builtin_catalog
autoplay_sdk.proactive_triggers.context_source	autoplay_sdk.proactive.triggers.context_source
autoplay_sdk.proactive_triggers.defaults	autoplay_sdk.proactive.triggers.defaults
autoplay_sdk.proactive_triggers.entity	autoplay_sdk.proactive.triggers.entity
autoplay_sdk.proactive_triggers.judge	autoplay_sdk.proactive.triggers.judge
autoplay_sdk.proactive_triggers.pending_tour_offer	autoplay_sdk.proactive.triggers.pending_tour_offer
autoplay_sdk.proactive_triggers.predicate_trigger	autoplay_sdk.proactive.triggers.predicate_trigger
autoplay_sdk.proactive_triggers.proactive_intercom_config	autoplay_sdk.proactive.triggers.proactive_intercom_config
autoplay_sdk.proactive_triggers.quick_reply_match	autoplay_sdk.proactive.triggers.quick_reply_match
autoplay_sdk.proactive_triggers.registry	autoplay_sdk.proactive.triggers.registry
autoplay_sdk.proactive_triggers.scope	autoplay_sdk.proactive.triggers.scope
autoplay_sdk.proactive_triggers.section_activity	autoplay_sdk.proactive.triggers.section_activity
autoplay_sdk.proactive_triggers.tour_registry	autoplay_sdk.proactive.triggers.tour_registry
autoplay_sdk.proactive_triggers.trigger_config	autoplay_sdk.proactive.triggers.trigger_config
autoplay_sdk.proactive_triggers.triggers	autoplay_sdk.proactive.triggers.triggers
autoplay_sdk.proactive_triggers.triggers.canonical_ping_pong	autoplay_sdk.proactive.triggers.triggers.canonical_ping_pong
autoplay_sdk.proactive_triggers.triggers.scoped_canonical_ping_pong	autoplay_sdk.proactive.triggers.triggers.scoped_canonical_ping_pong
autoplay_sdk.proactive_triggers.triggers.section_playbook	autoplay_sdk.proactive.triggers.triggers.section_playbook
autoplay_sdk.proactive_triggers.triggers.user_page_dwell	autoplay_sdk.proactive.triggers.triggers.user_page_dwell
autoplay_sdk.proactive_triggers.types	autoplay_sdk.proactive.triggers.types
autoplay_sdk.proactive_triggers.url_scope	autoplay_sdk.proactive.triggers.url_scope

See Migration 0.7.4 for upgrade steps.

---

[0.7.3] — 2026-05-14

Documentation

• Added dedicated references for UserSessionIndex, compose_chat_pipeline(...), and build_copilot_app(...), including lifecycle details, endpoint status semantics, and failure troubleshooting.
• Updated Logging with explicit observability guidance for autoplay_sdk.chat_pipeline, autoplay_sdk.user_index, and autoplay_sdk.serve.fastapi, including recommended app-layer log points for self-hosted bridges.
• Added a clearer self-hosted quick-reference and troubleshooting section in README.md (repository package docs), covering primitive selection and common 404/identity/product-scope failure modes.

---

[0.7.2] — 2026-05-14

Removed

• TourDefinition.label and TourDefinition.user_tour_exists — these fields belong to proactive_intercom.messages, not the tour registry. Removed from the dataclass, to_dict, and from_dict. Legacy configs that still include these keys are silently ignored on parse.

Added

• TOUR_OFFER_QUICK_REPLY_BODY — constant ("Would you like me to show you?"); default body for the tour-offer Yes/No quick reply.
• tour_offer_quick_reply_body(integration_config) — single SDK source-of-truth for the tour-offer message body; reads integration_config.tour_offer_body for product-level overrides, falls back to the constant. Call this after resolve_tour_offer_for_inbound returns a non-None flow id. Both symbols exported from autoplay_sdk.proactive_triggers.

---

[0.7.1] — 2026-05-13

Added

• autoplay_sdk.install_skills — CLI command autoplay-install-skills that copies bundled Cursor/Claude agent skills into the current project. Supports --chatbot and --user-activity flags.
• autoplay_sdk/skills/ — 10 agent skill files shipped inside the wheel: autoplay-core, chatbot-ada, chatbot-intercom, chatbot-botpress, chatbot-dify, chatbot-crisp, chatbot-landbot, chatbot-tidio, activity-fullstory, activity-posthog.

Documentation

• Ada tutorial (docs/recipes/ada/), FullStory Streams tutorial (docs/recipes/fullstory/how-to-setup.mdx), and quickstart autoplay-install-skills tip block.

---

[0.7.0] — 2026-05-12

Added

• autoplay_sdk.agent_state_v2 — SessionState FSM with THINKING / PROACTIVE / REACTIVE states, timeout-only exit rules, and InvalidTransitionError. Coexists with v1 AgentStateMachine.
• autoplay_sdk.proactive_triggers.trigger_config — ProactiveTriggerConfig, TriggerMessage, and recursive ProactiveCriteria for config-driven proactive triggers.
• autoplay_sdk.proactive_triggers.tour_registry — TourDefinition and TourRegistry; per-tour interaction_timeout_s / cooldown_period_s overrides; get_by_user_tour_id().
• SessionState.record_tour_step(), SessionState.set_visual_guidance(), SessionState.tick(tour_registry=None).
• parse_tour_registry(integration_config, product_id) helper in proactive_intercom_config.

Changed

• integration_config.proactive_intercom — now a list of ProactiveTriggerConfig objects (was a single dict).
• TriggerMessage — renamed offers_tour → user_tour_exists, flow_id → user_tour_id; backward-compatible properties retained.

Documentation

• Intercom proactive triggers step 2, Agent session states — agent state v2 accordion.

---

[0.6.8] — 2026-05-05

• SDK branch release tag/version for current branch cut.
• AgentStateMachine.enter_reactive_from_user_message docs + behavior notes now include rejection logging and preserved InvalidTransitionError semantics.

---

[0.6.7] — 2026-04-30

Agent FSM, Intercom proactive quick_reply, autoplay_sdk.proactive_triggers (replaces integrations.proactive), registry timings/entity, context builders, scope validation, product-scoped context-store buckets, and proactive idle teardown for chat: run_proactive_idle_expiry, ProactiveIdleExpiryHooks, ProactiveIdleExpiryResult, Intercom DELETE /conversations/{id} helpers (build_intercom_delete_conversation_request, etc.).

For full Added / Changed / Breaking detail, see the same version in the repository CHANGELOG.md.

Removed

• autoplay_sdk.integrations.proactive — use autoplay_sdk.proactive_triggers (import paths and submodules mirror the old layout).

Added

• autoplay_sdk.agent_states — AgentState, AgentStateMachine, TaskProgress, SessionMetrics, InvalidTransitionError, InvalidSnapshotError; five-state FSM; transition_on_disengagement(); to_snapshot() / from_snapshot(); can_show_proactive_with_reason().
• autoplay_sdk.agent_states.AgentStateMachine — expire_proactive_to_thinking_if_idle.
• autoplay_sdk.integrations.intercom — quick_reply helpers, INTERCOM_PROACTIVE_QUICK_REPLY_DEFAULT_BODY, proactive_trigger_canonical_url_ping_pong, connector helpers for POST /intercom/proactive/{product_id}, IntercomProactivePolicyConfig.
• autoplay_sdk.proactive_triggers — ProactiveTriggerContext, ProactiveTriggerResult, registry, CanonicalPingPongTrigger, default_proactive_trigger_registry, timings (ProactiveTriggerTimings, ProactiveTriggerEntity, interaction_timeout_s, cooldown_s).
• autoplay_sdk.proactive_triggers.defaults — ProactiveTriggerIds, get_proactive_trigger_ids(), DEFAULT_PROACTIVE_QUICK_REPLY_BODY.
• PredicateProactiveTrigger; from_actions_payloads / from_slim_actions; DEFAULT_PROACTIVE_CONTEXT_* exports; scope (ScopePolicy, validation helpers); validate_scope (require_conversation).
• autoplay_sdk.context_store — actions_bucket_id, optional product_id on get, enrich, reset; composite _actions keys when ActionsPayload.product_id is set.

Changed

• autoplay_sdk.integrations.intercom — INTERCOM_PROACTIVE_QUICK_REPLY_DEFAULT_BODY aliases proactive_triggers.defaults.
• ProactiveTriggerContext — optional recent_actions, summaries, context_extra.
• from_slim_actions / from_actions_payloads — default scope_policy=STRICT (use LENIENT to relax).
• POST /intercom/proactive/{product_id} documented as always-on when authenticated (ENABLE_INTERCOM_PROACTIVE_PROMPTS removed).

Documentation

• Agent session states, Intercom integration, Proactive triggers, Authoring proactive triggers.

Breaking changes

• expire_proactive_to_thinking_if_idle — returns ProactiveIdleExpiryResult (use if result: / result.transitioned, not is True on the return value). See CHANGELOG.md.
• Migrate imports from autoplay_sdk.integrations.proactive to autoplay_sdk.proactive_triggers.
• Strict scope defaults; LENIENT for old permissive behaviour.
• Match product_id on context-store reads when payloads carry product_id.

---

[0.6.6] — 2026-04-23

Added

• SlimAction / ActionsPayload — optional conversation_id (Intercom thread when linked); merge semantics unchanged at batch level.

• autoplay_sdk.rag_query — query-time RAG assembly (assemble_rag_chat_context, providers, ChatContextAssembly, formatters).

• autoplay_sdk.prompts — versioned Adoption Copilot defaults (RAG_SYSTEM_PROMPT, REASONING_PROMPT, RESPONSE_PROMPT).

• autoplay_sdk.rag_query.watermark — delta activity watermarks for Intercom / connector chat.

• autoplay_sdk.prompts.intercom_readability — shared INTERCOM_READABILITY_RULES fragment for Messenger replies.

Changed

• Root __all__ documents query-time RAG vs ingestion RagPipeline.

• RAG_SYSTEM_PROMPT / RESPONSE_PROMPT (1.2) and connector INTERCOM_CHAT_PROMPT (5) — readability + guidance framing for product how-to questions.

• assemble_rag_chat_context — structured DEBUG / WARNING logging.

Documentation

• Support AI agent context assembly — delta activity and observability cross-links.

Breaking changes

None for JSON consumers — new fields remain optional.

---

[0.6.4] — 2026-04-23

Added

• SlimAction — optional per-action session_id, user_id, and email (aligned with batch-level payload identity). Present on each entry in actions for SSE, push webhooks, and typed parsing.

• RedisEventBuffer — serialized JSON now includes those fields per action so buffered events round-trip cleanly.

Documentation

• Payload schema and Typed payloads — document per-action identity fields; payload schema clarifies shared shape for SSE and push webhooks.

Breaking changes

None — new fields are optional (None when omitted).

---

[0.6.2] — 2026-04-16

Added

• POST /products terminal feedback — TTY-only Rich stderr spinner and stdout success/failure lines in post_register_product_payload; no output when stdout is not a TTY.

Changed

• run_product_onboarding — single POST /products; connector performs Redis + Render when configured. render_sync_performed reflects connector dual_write in the JSON response.
• unkey.py is now a default dependency — plain pip install autoplay-sdk includes operator onboarding (autoplay_sdk.admin / Unkey).

Removed

• autoplay-sdk[admin] extra — install autoplay-sdk only.

---

[0.6.1] — 2026-04-14

Added

• ConversationEventType (autoplay_sdk.chatbot) — enum for chatbot session-link event semantics (NEW / REPLY_EXISTING).
• BaseChatbotWriter session-link webhook flow — SESSION_LINK_WEBHOOK_TOPICS, extract_conversation_event(), _parse_session_link_webhook_payload() (subclasses override parse only).
• autoplay_sdk.integrations.intercom — webhook topic constants, intercom_chatbot_webhook_url(), optional format_reactive_session_link_script (no logging from this subpackage).

Removed

• format_proactive_session_start_script and the proactive /sessions/start snippet — use Intercom webhooks to POST /chatbot-webhook/{product_id}; optional format_reactive_session_link_script remains for POST /sessions/link.

Documentation

• Logging — logger hierarchy, app-owned logging configuration, third-party subclass guidance, changelog cross-link.
• README — logging section aligned with the above; metrics pointer (SdkMetricsHook).
• Intercom integration — SDK helpers and connector mapping (webhooks, optional snippet, inbox UX).

Breaking changes

• format_proactive_session_start_script removed from autoplay_sdk.integrations.intercom.

Deprecations

None.

---

[0.6.0] — 2026-04-13

Documentation

• BaseChatbotWriter — Note body format — BaseChatbotWriter now documents the full plain-text contract for _post_note bodies (header via format_chatbot_note_header, sorted 1-based action lines, binning vs post-link, empty list, summary notes). _format_note docstring points to that page as the single source of truth.

• Logging — New Logging reference page (module loggers, % formatting, exc_info, structured extra, secrets guidance including HTTP bodies, common logging mistakes). Quickstart links to it for discoverability.

Bug fixes / observability

• BaseChatbotWriter — pre-link flush failure warning now includes structured extra (session_id, product_id, conversation_id).

• BaseChatbotWriter — post-link debounced flush: if _post_note returns no part id after the debounce buffer was popped, logs a warning with the same extra shape and explains that this flush is not retried automatically.

Breaking changes

None.

Deprecations

None.

---

[0.5.0] — 2026-04-10

New features

• ActionsPayload.merge(payloads) — class method that merges a non-empty list of ActionsPayload objects for the same session into one. Actions are concatenated and re-indexed from 0; user_id/email resolved from the first non-None value; forwarded_at set to the latest timestamp. Raises ValueError on empty input.

• AsyncAgentContextWriter(debounce_ms=N) — new optional constructor parameter for a per-session trailing-edge accumulation window. When > 0, multiple add() calls arriving within the window are merged via ActionsPayload.merge() before write_actions is called, reducing destination API calls during event bursts. Default is 0 (no debounce — existing behaviour unchanged).

• BaseChatbotWriter (autoplay_sdk.chatbot) — new public base class providing the complete pre-link/post-link delivery policy for building chatbot destinations. Subclass it and implement _post_note and _redact_part; pre-link buffering (sliding window), at-link flush (binned note), and post-link debouncing are all included. IntercomChatbot in the event connector already extends this class.

Breaking changes

None. All changes are additive:

• AsyncAgentContextWriter.__init__ gains debounce_ms: int = 0 — existing code passing positional or keyword arguments is unaffected.
• ActionsPayload.merge() is a new class method; no existing method is renamed or removed.
• BaseChatbotWriter is a new public export; no existing symbols are removed.

Deprecations

None.

Bug fixes / error handling improvements

• BaseChatbotWriter.on_session_linked — now no-ops when the same conversation_id is passed again (idempotent guard). The product worker includes the conv_id on every batch for already-linked sessions; without this guard, each batch would cancel the in-flight 150ms post-link debounce task and restart the window, causing notes to be delayed indefinitely during fast user interactions.

• BaseChatbotWriter.on_session_linked — pre-link buffer (_pending) is now only cleared after _post_note confirms success (returns a non-None part id). Previously the buffer was popped before the API call; a transient Intercom failure would permanently lose those events. On failure the buffer is now preserved and the _conv_map entry is rolled back so the next on_session_linked call retries automatically.

• BaseChatbotWriter.write_actions: the post-link debounce asyncio.Task now has a done_callback that logs any unhandled exception at ERROR level with structured extra (previously silent — Python only emitted a DEBUG-level “Task exception was never retrieved”).

• AsyncAgentContextWriter._flush_session done-callback: now includes product_id in the log message and extra dict for structured log filtering.

Migration notes

AsyncAgentContextWriter + BaseChatbotWriter — avoid double-debouncing

BaseChatbotWriter already coalesces rapid write_actions() calls via its post_link_debounce_s window (default 150 ms). When wiring an AsyncAgentContextWriter to a BaseChatbotWriter subclass, keep debounce_ms=0 (the default):

# CORRECT — BaseChatbotWriter handles debouncing; no stacking needed
writer = AsyncAgentContextWriter(
    summarizer=summarizer,
    write_actions=chatbot_subclass.write_actions_cb,
    overwrite_with_summary=overwrite_cb,
    debounce_ms=0,   # ← default, explicit for clarity
)

# AVOID — stacks two debounce windows, adds latency without benefit
writer = AsyncAgentContextWriter(..., debounce_ms=200)

Use debounce_ms > 0 only when write_actions points to a raw destination with no internal coalescing (e.g. a direct Zendesk or Salesforce API call).

---

[0.4.0] — 2026-04-09

Bug fixes

• Fixed TOCTOU race in RedisEventBuffer._get_redis(): concurrent callers could each create their own connection pool; now serialised with asyncio.Lock and double-checked locking.
• Fixed AsyncSessionSummarizer.flush() cancellation safety: replaced sequential for q in queues: await q.join() with asyncio.gather(*[asyncio.shield(q.join()) for q in queues]) so all queues are drained even when the caller is cancelled.

Other

• Added CHANGELOG.md to document breaking changes and new features going forward.

---

[0.3.0] — 2026-04-09

Breaking changes

• AsyncSessionSummarizer.get_context(session_id) is now async — callers must await it.
• AsyncSessionSummarizer.reset(session_id) is now async — callers must await it.
• AsyncSessionSummarizer.active_sessions is now an async property — callers must await it.
• AsyncSessionSummarizer.add() now returns immediately — the LLM call is dispatched to a background worker queue rather than awaited inline. Code that relied on the LLM having completed by the time await add() returned must call await summarizer.flush() before inspecting state.

New features

• AsyncSessionSummarizer.flush() — waits for all queued payloads to be fully processed; cancellation-safe via asyncio.gather + asyncio.shield.
• SdkMetricsHook protocol (autoplay_sdk.metrics) — a @runtime_checkable Protocol that customers can implement to receive Prometheus / Datadog / OTEL counters for: dropped events, summarizer latency, Redis operation latency, queue depth, and semaphore timeouts.
• metrics= constructor parameter on ConnectorClient, AsyncConnectorClient, AsyncSessionSummarizer, and RedisEventBuffer.
• initial_backoff_s, max_backoff_s, max_retries constructor parameters on both SSE clients — exposes and documents the reconnect policy with configurable jitter-backed exponential backoff.
• Per-session ordering guarantee in AsyncSessionSummarizer — each session now has its own asyncio.Queue + background asyncio.Task worker, ensuring that concurrent add() calls for the same session are always processed in arrival order, even if an earlier LLM call fails.
• py.typed marker — the package is now PEP 561-compliant; static type-checkers will find type stubs automatically.

Bug fixes (v0.2.x → v0.3.0)

The following 24 items were addressed across two audit passes:

Concurrency & correctness

• Fixed AsyncSessionSummarizer ordering bug: concurrent adds during an LLM failure could produce out-of-order on_summary callbacks (replaced single lock with per-session queue).
• Fixed TOCTOU race in RedisEventBuffer._get_redis(): concurrent callers could each create their own connection pool; now serialised with asyncio.Lock and double-checked locking.
• Replaced asyncio.Semaphore._value (private API, breaks across CPython minor versions) with an explicit _TrackedSemaphore counter.
• Replaced asyncio.get_event_loop() (deprecated) with asyncio.get_running_loop() in app.py and async_client.py.
• Replaced asyncio.ensure_future() with loop.create_task() in async_client.py.
• Added done_callback on fire-and-forget asyncio.Tasks to log unhandled exceptions instead of silently swallowing them.

Error handling

• RedisEventBuffer._payload_from_json() now wraps json.loads in try/except json.JSONDecodeError; corrupt ZSET members no longer crash the drain loop.
• ConnectorClient now sets self._running = False on KeyboardInterrupt so callers can inspect the state after shutdown.
• All except clauses that were swallowing exceptions now pass exc_info=True to the logger so tracebacks appear in structured logs.

Data structures

• RedisEventBuffer ZSET members now carry a unique UUID prefix, preventing silent deduplication when two events arrive at the same millisecond timestamp.
• SessionSummarizer now deletes _history[session_id] and _counts[session_id] after summarisation to prevent unbounded memory growth.
• AsyncConnectorClient._session_semaphores changed from plain dict to collections.OrderedDict with LRU eviction to cap memory when many short-lived sessions are processed.

Redis connection management

• Extracted LazyRedisClient helper (storage/_redis.py) so all storage modules share one lazily-initialised, thread-safe Redis client instead of each implementing the same racy pattern.
• session_store now uses LazyRedisClient and exposes a SessionState.from_redis_link() classmethod that owns the full reconstruction logic (preventing silent field omissions on restore).
• SessionState gains an error: Optional[str] field to surface last-known error reason through the API.

Logging & observability

• Replaced custom _JsonFormatter in app.py that ignored extra={} fields with a correct implementation that merges them into the JSON line.
• All structured log calls now use extra={} dicts consistently.
• Metrics instrumentation added at every observability-relevant site: event drops, queue depth, semaphore timeouts, summarizer latency, Redis add/drain latency.

Package hygiene

• Added __all__ exports to __init__.py so from autoplay_sdk import * is well-defined.
• Added __version__ = "0.3.0" to __init__.py.
• Added py.typed marker for PEP 561 compliance.
• Removed dead _dropped_count / _total_count metrics fields that were incremented but never surfaced.
• Standardised public API: on_drop callback signature is now consistent across ConnectorClient, AsyncConnectorClient, and RedisEventBuffer.

---

[0.2.0] — prior

Initial internal release. No changelog maintained at this version.