agentscope-ai / agentscope-ai/QwenPaw
[Feature]: Add session lifecycle hooks (session.create, session.reset, etc.)
- Vorherrschende Sprache
- Python
- Sterne
- 34.9k
- Forks
- 3.1k
- Ø Merge
- 1 T. 15 Std.
- Gemergte PRs (30 T.)
- 225
Beschreibung
## Summary
Add conversation lifecycle hooks (especially `session.create`) to allow developers to register custom logic that runs automatically when new chat sessions are created, enabling personalized initialization, memory loading, context injection, and automated workflows without modifying core code.
## Component(s) Affected
- [x] Core / Backend (app, agents, config, providers, utils, local_models)
- [ ] Console (frontend web UI)
- [ ] Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
- [ ] Skills
- [ ] CLI
- [ ] Documentation (website)
- [ ] Tests
- [ ] CI/CD
- [ ] Scripts / Deploy
## Problem / Motivation
Currently, QwenPaw's plugin system supports `startup_hook` (gateway start) and `shutdown_hook` (gateway stop), but there is no hook for **conversation-level lifecycle events** like session creation, session reset, or session end.
This gap makes it difficult to:
- **Auto-load context**: Inject project-specific files, memory, or preferences when a new session starts
- **Personalize per-session**: Set up session-specific environment variables, tool configurations, or agent behaviors
- **Automate initialization**: Run scripts, fetch remote data, or warm up models on session creation
- **Track & audit**: Log session creation events for compliance, usage analytics, or debugging
Developers who want this behavior today must either modify core code (intrusive, hard to maintain) or rely on fragile workarounds like checking for session markers in heartbeat loops. A clean hook interface would solve this elegantly.
## Proposed Solution
### 1. Define Conversation Lifecycle Hook Points
Add the following lifecycle events to the conversation/session flow:
| Hook | Trigger | Typical Use |
|------|---------|-------------|
| `session.create` | New chat session created | Load context, inject memory, run init scripts |
| `session.reset` | Session history cleared | Reset state, clear caches |
| `session.end` | Session closed / idle timeout | Save state, cleanup, archive |
| `message.before` | Before processing user message | Sensitive check, prompt enhancement, filter |
| `message.after` | After generating response | Post-processing, logging, notification |
### 2. Extend Plugin API
Add registration methods to `PluginApi` (alongside existing `register_startup_hook` / `register_shutdown_hook`):
```python
# Register a session lifecycle hook
api.register_session_hook(
hook_name="session.create",
callback=self.on_session_create,
priority=100,
)
# Register a message lifecycle hook
api.register_message_hook(
hook_name="message.before",
callback=self.on_message_before,
priority=50,
)
```
Callback signature:
```python
async def on_session_create(session_id: str, agent_id: str, metadata: dict) -> None:
"""Called when a new session is created."""
pass
```
### 3. Configuration Support (Optional)
Allow hook registration via `config.json` for no-code use:
```json
{
"hooks": [
{
"event": "session.create",
"command": "python ~/.qwenpaw/hooks/init_context.py",
"args": ["{{session_id}}", "{{agent_id}}"]
}
]
}
```
### 4. Implementation Notes
- Add a `SessionHookRegistry` (similar to existing `PluginRegistry` startup/shutdown hooks)
- Fire hooks in priority order (lower = earlier)
- Support both sync and async callbacks
- Include timeout protection to prevent hooks from blocking session startup
- Add structured logging for hook execution (success/failure/duration)
## Alternatives Considered
1. **Modify core code directly**: Works but is intrusive, breaks on upgrades, and doesn't allow third-party extensions.
2. **Use heartbeat detection**: Poll and check for new session markers — fragile, adds latency, wastes tokens, and only works on heartbeat intervals (not real-time).
3. **Wrapper script around `qwenpaw daemon`**: Can intercept daemon start but cannot hook into individual session creation events within a running daemon.
4. **Reference OpenClaw's Events system**: OpenClaw already implements a rich events/hooks architecture including `session.create`. QwenPaw can adopt a similar pattern aligned with its existing plugin system, which already has the `PluginRegistry` infrastructure for managing hooks.
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.