[jeffdupont]

Why

TESTING.md §0.3 (launchdarkly/ai-sdks-monorepo#55, merged) says hooks go one way: experimental code may hook into core, but core never imports, names or calls experimental code. Python broke that in one place. Core lifecycle.py imported the skills module and called skills._clear_state() from shutdown() and _reset_for_testing(). The spec marks this as [shutdown hook: Python pending].

What

Same shape as the TypeScript SDK (shutdown-hooks.ts, registered from skills-core.ts):

• New core module shutdown_hooks.py. register_shutdown_hook(name, hook) and run_shutdown_hooks(). It names no feature. A hook that raises is logged and the rest still run. The test reset passes raise_errors=True, so a failed reset still fails the test, as before.
• skills_core.py registers clear_state when it loads, under the name "Agent Skills". The warning text is unchanged: Could not clear the Agent Skills state, still on the launchdarkly_ai_server.lifecycle logger.
• lifecycle.py no longer imports skills. shutdown() and _reset_for_testing() run the hooks. The shutdown() docstring no longer names the feature.
• agents.md says where the hook is registered.

No behaviour change: test_shutdown_clears_the_store still passes unchanged.

Tests

• test_core_does_not_import_experimental_code: a subprocess imports the package root, calls shutdown(), and asserts no launchdarkly_ai_server.skills*, .evaluations* or .experimental* module was loaded. With from . import skills put back in lifecycle.py, it fails ('launchdarkly_ai_server.skills_core' == '').
• The existing failure-isolation test now registers its own failing hook, plus a second hook, and checks that the second still runs.
• uv run pytest: 2462 passed, 12 skipped. ruff check, ruff format --check and mypy packages/*/src are clean.

Follow-up

Once this merges, remove the [shutdown hook: Python pending] note from TESTING.md §0.3 in the monorepo.

🤖 Generated with Claude Code

---

Note

Overview
Refactors how experimental state is cleared on shutdown so core lifecycle no longer imports Agent Skills. Previously lifecycle.py imported skills and called skills._clear_state() directly, which violated TESTING.md §0.3 (core must not import experimental code).

New shutdown_hooks module exposes register_shutdown_hook and run_shutdown_hooks. Experimental modules register cleanup at import time; shutdown() and _reset_for_testing() invoke all hooks. Hook failures are logged (with the hook’s registered name) and do not abort shutdown; test reset uses raise_errors=True to preserve strict cleanup behavior.

skills_core registers clear_state as the "Agent Skills" hook on load, so store/emitter teardown still happens when skills code has been imported, without lifecycle naming skills.

Tests add a subprocess check that shutdown() alone does not load skills*, evaluations*, or experimental* modules, and broaden the failure-isolation test to assert remaining hooks still run after one hook raises.

^{Reviewed by Cursor Bugbot for commit 700a089. Bugbot is set up for automated code reviews on this repo. Configure here.}