Changelog

​

[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

​

[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

​

[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

​

[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

​

[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

​

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)

​

[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

​

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

​

[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

​

[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

​

[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

​

Deprecations

​

[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

• 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

​

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

# 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)

​

[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)

• 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.

• 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.

• 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.

• 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.

• 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.

• 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