feat(extension): add lifecycle event contracts

[omarluq]

Summary

• add runtime-neutral lifecycle event names, payload/result structs, and dispatch helper
• expose lifecycle payloads to Lua handlers through the existing extension host
• document the lifecycle/tool/context seam roadmap and execution kanban

Validation

• mise exec -- go test ./...
• mise exec -- task build
• mise exec -- task ci
• cr review --agent -t uncommitted --base main

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d91eac64-8acd-49bd-b31f-9cfa135bb891

📥 Commits

Reviewing files that changed from the base of the PR and between bb1e41ffbf72cd16b1f66fcd04ee08bb7680f590 and 275ee9e.

📒 Files selected for processing (5)

• docs/extension-api.md
• docs/extension-roadmap.md
• docs/runtime-architecture.md
• internal/extension/lifecycle.go
• internal/extension/lifecycle_test.go

✅ Files skipped from review due to trivial changes (2)

• docs/runtime-architecture.md
• docs/extension-roadmap.md

🚧 Files skipped from review as they are similar to previous changes (3)

• internal/extension/lifecycle_test.go
• docs/extension-api.md
• internal/extension/lifecycle.go

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation describing planned agent lifecycle events for extensions, covering session, input, turn, context, provider, and tool execution phases.
  • Updated architecture roadmap with phased implementation strategy for lifecycle events and tool middleware capabilities.

Walkthrough

This pull request introduces a complete agent lifecycle event system. It documents planned event groups and delivery phases across the roadmap, implements typed Go contracts and a handler dispatch loop, and validates behavior with comprehensive tests covering priority ordering, handler stopping, error aggregation, and validation.

Changes

Lifecycle Event System

Layer / File(s)	Summary
Roadmap and planning documentation docs/extension-api.md, docs/extension-roadmap.md, docs/runtime-architecture.md	Extension API documentation defines event groups (session, input, turn, context, provider, tool, message), mutation policies, and constraints. Extension and runtime architecture roadmaps detail Phase 5 incremental implementation with runtime-neutral Go contracts, sub-phases for typed contracts and provider hooks, Phase 6 tool middleware and registry unification, delivery sequence, and design constraints for bounding, redaction, error visibility, and test coverage.
Lifecycle event contracts and types internal/extension/lifecycle.go	LifecycleEventName string type with 20 exported constants for session, resource discovery, input, agent, turn, context building, provider, tool, and messaging phases. LifecycleEvent and LifecycleDispatchResult data structures capture event details and dispatch outcomes. LifecycleDispatcher interface defines the dispatch contract.
Lifecycle dispatch implementation internal/extension/lifecycle.go	Manager.DispatchLifecycle validates event names, initializes results with cloned payloads, iterates over Lua-registered handlers in priority order, invokes each with a Lua event table, aggregates errors, applies Lua status/payload updates, and stops early on handler signal. Helper functions build Lua input tables and interpret Lua result fields for consumed/stopped flags and payload replacement.
Lifecycle dispatch tests internal/extension/lifecycle_test.go	Four tests validate handler priority ordering and payload aggregation, early termination on stop signal, error collection and propagation, and rejection of empty event names. Tests set up Lua-defined extensions and assert HandlerCount, Consumed, Stopped, Duration, Errors, and Payload fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A lifecycle for every season,
From session start to shutdown's reason,
With Lua handlers dancing in line,
Payloads flowing, mutations refined—
The system takes shape, the architecture shines! ✨

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'feat(extension): add lifecycle event contracts' clearly and concisely summarizes the main change: adding lifecycle event type contracts to the extension system.
Description check	✅ Passed	The PR description is directly related to the changeset, covering the three main aspects: runtime-neutral lifecycle event structures, Lua handler exposure, and documentation of the implementation roadmap.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/lifecycle-event-contracts

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

Codecov Report

❌ Patch coverage is 86.27451% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 56.93%. Comparing base (d37e548) to head (275ee9e).

Files with missing lines	Patch %	Lines
internal/extension/lifecycle.go	86.27%	4 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #21      +/-   ##
==========================================
+ Coverage   56.79%   56.93%   +0.14%     
==========================================
  Files         158      159       +1     
  Lines       15521    15572      +51     
==========================================
+ Hits         8815     8866      +51     
+ Misses       5754     5752       -2     
- Partials      952      954       +2     

Flag	Coverage Δ
unittests	56.93% <86.27%> (+0.14%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

🧹 Nitpick comments (1)

internal/extension/lifecycle_test.go (1)

13-100: ⚡ Quick win

Prefer table-driven subtests for these core lifecycle dispatch scenarios.

The four cases are strongly pattern-aligned; consolidating them into one table-driven test will reduce duplication and make additional edge cases cheaper to add.

As per coding guidelines **/*_test.go: Prefer table-driven tests for core behavior and regression tests for terminal rendering bugs.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@internal/extension/lifecycle_test.go` around lines 13 - 100, Consolidate the
four similar tests (TestManager_DispatchLifecycleRunsHandlersInPriorityOrder,
TestManager_DispatchLifecycleCanStopHandlers,
TestManager_DispatchLifecycleCollectsHandlerErrors,
TestManager_DispatchLifecycleRequiresName) into a single table-driven test that
iterates cases describing input (either a Lua script passed to loadTestExtension
or use of extension.NewManager), the LifecycleEvent to dispatch, and expected
outcomes (expected Name/Payload values, HandlerCount, Errors length/contents,
Consumed/Stopped flags, and whether an error is expected). Implement each case
as a t.Run subtest and reuse manager.DispatchLifecycle, loadTestExtension, and
extension.LifecycleEvent in the case runner; for the RequiresName case use
extension.NewManager and t.Cleanup(manager.Shutdown). Ensure assertions inside
each subtest check only the fields relevant to that case (e.g., check
result.Errors when an error is expected) so the consolidated test covers all
previous expectations without duplicating setup.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@internal/extension/lifecycle_test.go`:
- Around line 13-100: Consolidate the four similar tests
(TestManager_DispatchLifecycleRunsHandlersInPriorityOrder,
TestManager_DispatchLifecycleCanStopHandlers,
TestManager_DispatchLifecycleCollectsHandlerErrors,
TestManager_DispatchLifecycleRequiresName) into a single table-driven test that
iterates cases describing input (either a Lua script passed to loadTestExtension
or use of extension.NewManager), the LifecycleEvent to dispatch, and expected
outcomes (expected Name/Payload values, HandlerCount, Errors length/contents,
Consumed/Stopped flags, and whether an error is expected). Implement each case
as a t.Run subtest and reuse manager.DispatchLifecycle, loadTestExtension, and
extension.LifecycleEvent in the case runner; for the RequiresName case use
extension.NewManager and t.Cleanup(manager.Shutdown). Ensure assertions inside
each subtest check only the fields relevant to that case (e.g., check
result.Errors when an error is expected) so the consolidated test covers all
previous expectations without duplicating setup.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 707267a9-bdbf-4075-b8dd-3d4d36ce4946

📥 Commits

Reviewing files that changed from the base of the PR and between d37e548 and bb1e41ffbf72cd16b1f66fcd04ee08bb7680f590.

📒 Files selected for processing (6)

• TODO.md
• docs/extension-api.md
• docs/extension-roadmap.md
• docs/runtime-architecture.md
• internal/extension/lifecycle.go
• internal/extension/lifecycle_test.go

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud