docs: note new-session trigger for mission toolset reload
This commit is contained in:
Jason Woltje
@@ -14,45 +14,45 @@
|
||||
|
||||
### What Mosaic has that Hermes needs
|
||||
|
||||
| Mosaic Component | What it does | Natural Hermes home | Why |
|
||||
|---|---|---|---|
|
||||
| `packages/coord` (mission.ts) | Mission CRUD, session tracking, milestone state | **Hermes toolset: `mission`** | Mission state is session-scoped, not gateway-scoped. Hermes sessions already have identity, process tracking, and context windows. |
|
||||
| `packages/coord` (tasks-file.ts) | Parse/write TASKS.md tables | **Hermes toolset: `mission`** (same) | Hermes already reads/writes files. The TASKS.md parser is ~300 lines of pure string manipulation — trivial Python port. |
|
||||
| `packages/coord` (runner.ts) | Spawn claude/codex workers with continuation prompts | **Already covered by `delegate_task`** | Hermes delegate_task already does isolated subagent spawning with restricted toolsets. The runner's "find next task and build continuation prompt" logic moves into a tool-call. |
|
||||
| `packages/coord` (status.ts) | Mission health, task progress, next task | **Hermes toolset: `mission`** (same) | Status readout fits naturally as a tool-call. No gateway needed. |
|
||||
| `packages/prdy` | PRD generation wizard | **Hermes skill: `prdy`** | PRD generation is a prompt + template problem, not infrastructure. A Hermes skill with templates is the right fit. |
|
||||
| `plugins/mosaic-framework` | before_agent_start + subagent_spawning hooks | **Hermes system prompt injection** | Hermes already injects system context via skills and config. The framework preamble and worktree rules become standard Hermes skills loaded by the orchestrator profile. |
|
||||
| `plugins/macp` | OpenClaw ACP bridge (spawn codex/claude) | **Already covered by `delegate_task` + ACP** | Hermes already has ACP support and delegate_task. The MACP bridge is redundant when running natively in Hermes. |
|
||||
| Churn detection (planned) | Detect compaction loops, repeated tool calls, no progress | **Hermes middleware** | This needs to live inside Hermes's turn loop where it can observe tool-call patterns. Mosaic can't see this from outside. |
|
||||
| Handoff packet (planned) | Structured context summary for session rotation | **Hermes toolset: `mission`** | Handoff is a serialization of mission + session state. Hermes owns the session, so it should own the handoff. |
|
||||
| Mosaic Component | What it does | Natural Hermes home | Why |
|
||||
| -------------------------------- | --------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `packages/coord` (mission.ts) | Mission CRUD, session tracking, milestone state | **Hermes toolset: `mission`** | Mission state is session-scoped, not gateway-scoped. Hermes sessions already have identity, process tracking, and context windows. |
|
||||
| `packages/coord` (tasks-file.ts) | Parse/write TASKS.md tables | **Hermes toolset: `mission`** (same) | Hermes already reads/writes files. The TASKS.md parser is ~300 lines of pure string manipulation — trivial Python port. |
|
||||
| `packages/coord` (runner.ts) | Spawn claude/codex workers with continuation prompts | **Already covered by `delegate_task`** | Hermes delegate_task already does isolated subagent spawning with restricted toolsets. The runner's "find next task and build continuation prompt" logic moves into a tool-call. |
|
||||
| `packages/coord` (status.ts) | Mission health, task progress, next task | **Hermes toolset: `mission`** (same) | Status readout fits naturally as a tool-call. No gateway needed. |
|
||||
| `packages/prdy` | PRD generation wizard | **Hermes skill: `prdy`** | PRD generation is a prompt + template problem, not infrastructure. A Hermes skill with templates is the right fit. |
|
||||
| `plugins/mosaic-framework` | before_agent_start + subagent_spawning hooks | **Hermes system prompt injection** | Hermes already injects system context via skills and config. The framework preamble and worktree rules become standard Hermes skills loaded by the orchestrator profile. |
|
||||
| `plugins/macp` | OpenClaw ACP bridge (spawn codex/claude) | **Already covered by `delegate_task` + ACP** | Hermes already has ACP support and delegate_task. The MACP bridge is redundant when running natively in Hermes. |
|
||||
| Churn detection (planned) | Detect compaction loops, repeated tool calls, no progress | **Hermes middleware** | This needs to live inside Hermes's turn loop where it can observe tool-call patterns. Mosaic can't see this from outside. |
|
||||
| Handoff packet (planned) | Structured context summary for session rotation | **Hermes toolset: `mission`** | Handoff is a serialization of mission + session state. Hermes owns the session, so it should own the handoff. |
|
||||
|
||||
### What Hermes already has that replaces Mosaic infrastructure
|
||||
|
||||
| Mosaic concept | Hermes equivalent | Notes |
|
||||
|---|---|---|
|
||||
| Gateway (NestJS) | Hermes gateway | Hermes already has a gateway with WebSocket, Discord, Telegram, CLI. No need for a second one. |
|
||||
| Pi SDK agent runtime | Hermes agent loop | Hermes IS the agent runtime. OpenClaw's Pi SDK is a different runtime that Mosaic targets. |
|
||||
| MACP ACP bridge | `delegate_task` + ACP tools | Same capability, already native. |
|
||||
| Session identity | Hermes session IDs + process_registry | Hermes already tracks session identity, PIDs, and background processes. |
|
||||
| Task execution board | Hermes Kanban | Fully functional SQLite-backed Kanban with dispatcher, triage, events, comments. |
|
||||
| Worker spawning | Hermes dispatcher + cron | Kanban dispatcher + cron already handle this. |
|
||||
| Context injection | Hermes skills + system prompt | Skills are loaded at session start and injected into context. Exactly what mosaic-framework plugin does. |
|
||||
| File checkpoints | Hermes checkpoint_manager | Already tracks file mutations with shadow git. |
|
||||
| Mosaic concept | Hermes equivalent | Notes |
|
||||
| -------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| Gateway (NestJS) | Hermes gateway | Hermes already has a gateway with WebSocket, Discord, Telegram, CLI. No need for a second one. |
|
||||
| Pi SDK agent runtime | Hermes agent loop | Hermes IS the agent runtime. OpenClaw's Pi SDK is a different runtime that Mosaic targets. |
|
||||
| MACP ACP bridge | `delegate_task` + ACP tools | Same capability, already native. |
|
||||
| Session identity | Hermes session IDs + process_registry | Hermes already tracks session identity, PIDs, and background processes. |
|
||||
| Task execution board | Hermes Kanban | Fully functional SQLite-backed Kanban with dispatcher, triage, events, comments. |
|
||||
| Worker spawning | Hermes dispatcher + cron | Kanban dispatcher + cron already handle this. |
|
||||
| Context injection | Hermes skills + system prompt | Skills are loaded at session start and injected into context. Exactly what mosaic-framework plugin does. |
|
||||
| File checkpoints | Hermes checkpoint_manager | Already tracks file mutations with shadow git. |
|
||||
|
||||
### What Mosaic keeps as its own entity
|
||||
|
||||
| Component | Why it stays in Mosaic |
|
||||
|---|---|
|
||||
| `apps/gateway` | NestJS API surface — Mosaic's web platform offering |
|
||||
| `apps/web` | Next.js dashboard — Mosaic's UI offering |
|
||||
| `packages/types` | Shared TS contracts for Mosaic gateway plugins |
|
||||
| `packages/db` | Drizzle ORM + PG — Mosaic's data layer |
|
||||
| `packages/auth` | BetterAuth — Mosaic's auth system |
|
||||
| `packages/brain` | PG-backed data layer for Mosaic web app |
|
||||
| `packages/queue` | Valkey task queue for Mosaic gateway |
|
||||
| `plugins/discord` | OpenClaw Discord plugin |
|
||||
| `plugins/telegram` | OpenClaw Telegram plugin |
|
||||
| `packages/mosaic` CLI | The `mosaic` CLI — Mosaic's own command surface |
|
||||
| Component | Why it stays in Mosaic |
|
||||
| --------------------- | --------------------------------------------------- |
|
||||
| `apps/gateway` | NestJS API surface — Mosaic's web platform offering |
|
||||
| `apps/web` | Next.js dashboard — Mosaic's UI offering |
|
||||
| `packages/types` | Shared TS contracts for Mosaic gateway plugins |
|
||||
| `packages/db` | Drizzle ORM + PG — Mosaic's data layer |
|
||||
| `packages/auth` | BetterAuth — Mosaic's auth system |
|
||||
| `packages/brain` | PG-backed data layer for Mosaic web app |
|
||||
| `packages/queue` | Valkey task queue for Mosaic gateway |
|
||||
| `plugins/discord` | OpenClaw Discord plugin |
|
||||
| `plugins/telegram` | OpenClaw Telegram plugin |
|
||||
| `packages/mosaic` CLI | The `mosaic` CLI — Mosaic's own command surface |
|
||||
|
||||
---
|
||||
|
||||
@@ -61,7 +61,7 @@
|
||||
### New files under `/opt/hermes/tools/`
|
||||
|
||||
```
|
||||
mission_tools.py — Tool-call surface (mission_create, mission_status,
|
||||
mission_tools.py — Tool-call surface (mission_create, mission_status,
|
||||
mission_next_task, mission_update_task, mission_handoff,
|
||||
mission_resume)
|
||||
mission_state.py — State management (read/write mission.json, parse TASKS.md,
|
||||
@@ -73,14 +73,14 @@ mission_handoff.py — Handoff packet generation and loading
|
||||
|
||||
### Tool-calls exposed to the agent
|
||||
|
||||
| Tool | What it does | When the agent calls it |
|
||||
|---|---|---|
|
||||
| `mission_create` | Initialize mission.json + TASKS.md + MISSION-MANIFEST.md in a project dir | When starting a new mission |
|
||||
| `mission_status` | Read current mission state, milestone progress, next task, active session | At session start, or when checking progress |
|
||||
| `mission_next_task` | Find the next `not-started` task whose dependencies are met, return its full spec | When the agent needs work to do |
|
||||
| `mission_update_task` | Update a task row status in TASKS.md | When completing or blocking a task |
|
||||
| `mission_handoff` | Generate a handoff packet from current session context + mission state | Before session rotation or at session end |
|
||||
| `mission_resume` | Load a handoff packet and inject it as context for the new session | At session start after rotation |
|
||||
| Tool | What it does | When the agent calls it |
|
||||
| --------------------- | --------------------------------------------------------------------------------- | ------------------------------------------- |
|
||||
| `mission_create` | Initialize mission.json + TASKS.md + MISSION-MANIFEST.md in a project dir | When starting a new mission |
|
||||
| `mission_status` | Read current mission state, milestone progress, next task, active session | At session start, or when checking progress |
|
||||
| `mission_next_task` | Find the next `not-started` task whose dependencies are met, return its full spec | When the agent needs work to do |
|
||||
| `mission_update_task` | Update a task row status in TASKS.md | When completing or blocking a task |
|
||||
| `mission_handoff` | Generate a handoff packet from current session context + mission state | Before session rotation or at session end |
|
||||
| `mission_resume` | Load a handoff packet and inject it as context for the new session | At session start after rotation |
|
||||
|
||||
### Toolset registration
|
||||
|
||||
@@ -89,7 +89,6 @@ The `mission` toolset follows the same pattern as `kanban`:
|
||||
1. **Gating**: Tools are available when:
|
||||
- The profile has `mission` in its toolsets config, OR
|
||||
- A `HERMES_MISSION_DIR` env var is set (cron/dispatcher spawned workers)
|
||||
|
||||
2. **File conventions**: The toolset reads/writes the same file formats as Mosaic `packages/coord`:
|
||||
- `.mosaic/orchestrator/mission.json` — mission state
|
||||
- `docs/TASKS.md` — task table
|
||||
@@ -108,6 +107,7 @@ Churn detection lives in Hermes's turn loop, NOT as a tool-call. It observes:
|
||||
- Repeated permission denials
|
||||
|
||||
When churn score exceeds threshold:
|
||||
|
||||
1. `mission_handoff` is called automatically
|
||||
2. Session is rotated (fresh context window)
|
||||
3. `mission_resume` is called in the new session
|
||||
@@ -120,58 +120,58 @@ This is new infrastructure that only Hermes can provide (Mosaic runs outside the
|
||||
|
||||
### Phase 1: Core state management (Python port of coord)
|
||||
|
||||
| Task | Files | Estimate |
|
||||
|---|---|---|
|
||||
| 1.1 Port mission.json read/write to Python | `mission_state.py` | 2h |
|
||||
| 1.2 Port TASKS.md parser to Python | `mission_state.py` | 2h |
|
||||
| 1.3 Port MISSION-MANIFEST.md reader to Python | `mission_state.py` | 1h |
|
||||
| 1.4 Implement `mission_create` tool-call | `mission_tools.py` | 1h |
|
||||
| 1.5 Implement `mission_status` tool-call | `mission_tools.py` | 1h |
|
||||
| 1.6 Implement `mission_next_task` tool-call | `mission_tools.py` | 1h |
|
||||
| 1.7 Implement `mission_update_task` tool-call | `mission_tools.py` | 1h |
|
||||
| 1.8 Register `mission` toolset in Hermes registry | `tools/registry.py` | 30m |
|
||||
| 1.9 Add `mission` to orchestrator profile toolsets | `config.yaml` | 10m |
|
||||
| 1.10 Write unit tests for mission_state | `tests/test_mission_state.py` | 2h |
|
||||
| 1.11 Write unit tests for TASKS.md parser | `tests/test_tasks_parser.py` | 1h |
|
||||
| Task | Files | Estimate |
|
||||
| -------------------------------------------------- | ----------------------------- | -------- |
|
||||
| 1.1 Port mission.json read/write to Python | `mission_state.py` | 2h |
|
||||
| 1.2 Port TASKS.md parser to Python | `mission_state.py` | 2h |
|
||||
| 1.3 Port MISSION-MANIFEST.md reader to Python | `mission_state.py` | 1h |
|
||||
| 1.4 Implement `mission_create` tool-call | `mission_tools.py` | 1h |
|
||||
| 1.5 Implement `mission_status` tool-call | `mission_tools.py` | 1h |
|
||||
| 1.6 Implement `mission_next_task` tool-call | `mission_tools.py` | 1h |
|
||||
| 1.7 Implement `mission_update_task` tool-call | `mission_tools.py` | 1h |
|
||||
| 1.8 Register `mission` toolset in Hermes registry | `tools/registry.py` | 30m |
|
||||
| 1.9 Add `mission` to orchestrator profile toolsets | `config.yaml` | 10m |
|
||||
| 1.10 Write unit tests for mission_state | `tests/test_mission_state.py` | 2h |
|
||||
| 1.11 Write unit tests for TASKS.md parser | `tests/test_tasks_parser.py` | 1h |
|
||||
|
||||
**Phase 1 estimate:** ~13h
|
||||
|
||||
### Phase 2: Handoff and session continuity
|
||||
|
||||
| Task | Files | Estimate |
|
||||
|---|---|---|
|
||||
| 2.1 Define handoff packet schema (JSON) | `mission_handoff.py` | 1h |
|
||||
| 2.2 Implement `mission_handoff` tool-call | `mission_handoff.py`, `mission_tools.py` | 2h |
|
||||
| 2.3 Implement `mission_resume` tool-call | `mission_handoff.py`, `mission_tools.py` | 2h |
|
||||
| 2.4 Wire handoff into session start (auto-resume) | agent loop hook | 2h |
|
||||
| 2.5 Write tests for handoff round-trip | `tests/test_mission_handoff.py` | 1h |
|
||||
| Task | Files | Estimate |
|
||||
| ------------------------------------------------- | ---------------------------------------- | -------- |
|
||||
| 2.1 Define handoff packet schema (JSON) | `mission_handoff.py` | 1h |
|
||||
| 2.2 Implement `mission_handoff` tool-call | `mission_handoff.py`, `mission_tools.py` | 2h |
|
||||
| 2.3 Implement `mission_resume` tool-call | `mission_handoff.py`, `mission_tools.py` | 2h |
|
||||
| 2.4 Wire handoff into session start (auto-resume) | agent loop hook | 2h |
|
||||
| 2.5 Write tests for handoff round-trip | `tests/test_mission_handoff.py` | 1h |
|
||||
|
||||
**Phase 2 estimate:** ~8h
|
||||
|
||||
### Phase 3: Churn detection
|
||||
|
||||
| Task | Files | Estimate |
|
||||
|---|---|---|
|
||||
| 3.1 Define churn signal weights and thresholds | `mission_churn.py` | 1h |
|
||||
| 3.2 Implement tool-loop detector (consecutive identical calls) | `mission_churn.py` | 2h |
|
||||
| 3.3 Implement compaction pressure detector | `mission_churn.py` | 1h |
|
||||
| 3.4 Implement progress scorer (file state delta) | `mission_churn.py` | 2h |
|
||||
| 3.5 Wire churn scoring into agent turn loop | agent loop middleware | 2h |
|
||||
| 3.6 Implement auto-rotation trigger | agent loop + handoff | 2h |
|
||||
| 3.7 Write tests for churn scoring | `tests/test_mission_churn.py` | 1h |
|
||||
| Task | Files | Estimate |
|
||||
| -------------------------------------------------------------- | ----------------------------- | -------- |
|
||||
| 3.1 Define churn signal weights and thresholds | `mission_churn.py` | 1h |
|
||||
| 3.2 Implement tool-loop detector (consecutive identical calls) | `mission_churn.py` | 2h |
|
||||
| 3.3 Implement compaction pressure detector | `mission_churn.py` | 1h |
|
||||
| 3.4 Implement progress scorer (file state delta) | `mission_churn.py` | 2h |
|
||||
| 3.5 Wire churn scoring into agent turn loop | agent loop middleware | 2h |
|
||||
| 3.6 Implement auto-rotation trigger | agent loop + handoff | 2h |
|
||||
| 3.7 Write tests for churn scoring | `tests/test_mission_churn.py` | 1h |
|
||||
|
||||
**Phase 3 estimate:** ~11h
|
||||
|
||||
### Phase 4: Kanban bridge + CLI surface
|
||||
|
||||
| Task | Files | Estimate |
|
||||
|---|---|---|
|
||||
| 4.1 Implement TASKS.md → Kanban sync (one-way first) | `mission_kanban_sync.py` | 2h |
|
||||
| 4.2 Add `hermes mission` CLI subcommand | `mission_cli.py` | 2h |
|
||||
| 4.3 Add `hermes mission status` command | `mission_cli.py` | 1h |
|
||||
| 4.4 Add `hermes mission init` command | `mission_cli.py` | 1h |
|
||||
| 4.5 Add `hermes mission handoff` command | `mission_cli.py` | 1h |
|
||||
| 4.6 Add `hermes mission resume` command | `mission_cli.py` | 1h |
|
||||
| Task | Files | Estimate |
|
||||
| ---------------------------------------------------- | ------------------------ | -------- |
|
||||
| 4.1 Implement TASKS.md → Kanban sync (one-way first) | `mission_kanban_sync.py` | 2h |
|
||||
| 4.2 Add `hermes mission` CLI subcommand | `mission_cli.py` | 2h |
|
||||
| 4.3 Add `hermes mission status` command | `mission_cli.py` | 1h |
|
||||
| 4.4 Add `hermes mission init` command | `mission_cli.py` | 1h |
|
||||
| 4.5 Add `hermes mission handoff` command | `mission_cli.py` | 1h |
|
||||
| 4.6 Add `hermes mission resume` command | `mission_cli.py` | 1h |
|
||||
|
||||
**Phase 4 estimate:** ~8h
|
||||
|
||||
|
||||
Reference in New Issue
Block a user