mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 20:01:09 +02:00
docs: update tool coverage table + server-side research + templates
Catches up all docs with the current state of the AI tool system. services/mana-ai/CLAUDE.md: - New v0.6 status section documenting NewsResearchClient, pre-planning research injection, config.manaApiUrl, and the full 28-tool / 11-module inventory (17 propose + 11 auto). apps/mana/CLAUDE.md: - New "Tool Coverage" table in the AI Workbench section listing all tools per module with their policy (propose vs auto). - New "Templates" subsection documenting the two-section gallery (agent vs workbench templates), the seed-handler registry, and the current handlers (meditate, habits, goals). - Architecture cross-reference updated to include §23. docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md: - §23.2 gains a "Server-Side Research (mana-ai, ab v0.6)" subsection explaining how NewsResearchClient mirrors the client-side research pre-step: same endpoints, same trigger regex, but HTTP-direct from the Docker network instead of SvelteKit-internal. docs/plans/README.md: - workbench-templates.md added to the roadmap table (T1 shipped). - Multi-agent description updated to mention 28 tools + server-side web-research. - Architecture cross-reference includes §23. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
2ead0f36df
commit
d83fc370a0
4 changed files with 56 additions and 3 deletions
|
|
@ -183,7 +183,36 @@ The companion is a **second actor** that works alongside the human in every modu
|
||||||
- **Scene lens** — workbench scenes can bind to an agent via `scene.viewingAsAgentId` (context menu → "An Agent binden…"). Pure UI lens, not a data-scope change. `SceneAppBar` shows the agent avatar on bound scene tabs.
|
- **Scene lens** — workbench scenes can bind to an agent via `scene.viewingAsAgentId` (context menu → "An Agent binden…"). Pure UI lens, not a data-scope change. `SceneAppBar` shows the agent avatar on bound scene tabs.
|
||||||
- **Workbench timeline** — `/ai-workbench` renders every AI-attributed event grouped by mission iteration with per-**agent** filter, per-module, per-mission. Each bucket header shows agent avatar + name + mission title. Per-bucket **Revert button** undoes the iteration's writes via `data/ai/revert/` (TaskCreated → delete, TaskCompleted → uncomplete, etc., newest-first). Separate **"Datenzugriff"** tab exposes the server-side decrypt audit (for missions with Key-Grants).
|
- **Workbench timeline** — `/ai-workbench` renders every AI-attributed event grouped by mission iteration with per-**agent** filter, per-module, per-mission. Each bucket header shows agent avatar + name + mission title. Per-bucket **Revert button** undoes the iteration's writes via `data/ai/revert/` (TaskCreated → delete, TaskCompleted → uncomplete, etc., newest-first). Separate **"Datenzugriff"** tab exposes the server-side decrypt audit (for missions with Key-Grants).
|
||||||
|
|
||||||
Full architecture (Planner prompt + parser in `@mana/shared-ai`, server-side runner, Postgres actor column, materialized snapshots, Multi-Agent gating, Prometheus metrics + status.mana.how integration): [`docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md`](../../docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md) §20 (AI Workbench) + §21 (Mission Grants) + §22 (Multi-Agent Workbench).
|
### Tool Coverage (28 tools, 11 modules)
|
||||||
|
|
||||||
|
Agents interact with the app through tools — each one either auto (executes silently during reasoning) or propose (creates a Proposal card the user must approve). Canonical list in `@mana/shared-ai/src/policy/proposable-tools.ts`; server-side definitions in `services/mana-ai/src/planner/tools.ts`; webapp auto-tool list in `src/lib/data/ai/policy.ts`.
|
||||||
|
|
||||||
|
| Module | Propose | Auto |
|
||||||
|
|--------|---------|------|
|
||||||
|
| todo | `create_task`, `complete_task`, `complete_tasks_by_title` | `get_task_stats`, `list_tasks` |
|
||||||
|
| calendar | `create_event` | `get_todays_events` |
|
||||||
|
| notes | `create_note`, `update_note`, `append_to_note`, `add_tag_to_note` | `list_notes` |
|
||||||
|
| places | `create_place`, `visit_place` | `get_places`, `location_log` |
|
||||||
|
| drink | `undo_drink` | `get_drink_progress`, `log_drink` |
|
||||||
|
| food | — | `nutrition_summary`, `log_meal` |
|
||||||
|
| news | `save_news_article` | — |
|
||||||
|
| news-research | `research_news` | — |
|
||||||
|
| journal | `create_journal_entry` | — |
|
||||||
|
| habits | `create_habit`, `log_habit` | `get_habits` |
|
||||||
|
| contacts | `create_contact` | `get_contacts` |
|
||||||
|
|
||||||
|
**Server-side web-research**: mana-ai calls mana-api's `/api/v1/news-research/discover` + `/search` directly before the planner prompt is built (pre-planning injection). Missions with research-keyword objectives get real article URLs + excerpts injected as a synthetic ResolvedInput. See `services/mana-ai/src/planner/news-research-client.ts`.
|
||||||
|
|
||||||
|
### Templates
|
||||||
|
|
||||||
|
Pre-configured starter-kits at `/agents/templates` — two sections:
|
||||||
|
|
||||||
|
- **Agent-Templates** (with AI): Recherche-Agent, Kontext-Agent, Today-Agent
|
||||||
|
- **Workbench-Templates** (no AI): Calmness, Fitness, Deep Work
|
||||||
|
|
||||||
|
Each template bundles: optional agent + optional scene layout + optional starter missions (paused) + optional per-module seeds. Template shape: `WorkbenchTemplate` in `@mana/shared-ai/src/agents/templates/types.ts`. Applicator: `src/lib/data/ai/agents/apply-template.ts`. Seed-handler registry: `src/lib/data/ai/agents/seed-registry.ts` — modules register via side-effect imports in `missions/setup.ts`. Current handlers: meditate, habits, goals. Plan: [`docs/plans/workbench-templates.md`](../../docs/plans/workbench-templates.md).
|
||||||
|
|
||||||
|
Full architecture (Planner prompt + parser in `@mana/shared-ai`, server-side runner, Postgres actor column, materialized snapshots, Multi-Agent gating, server-side web-research, Prometheus metrics + status.mana.how integration): [`docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md`](../../docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md) §20 (AI Workbench) + §21 (Mission Grants) + §22 (Multi-Agent Workbench).
|
||||||
|
|
||||||
## Reference Documents
|
## Reference Documents
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1993,6 +1993,18 @@ Chosen over the deep-research pipeline (`/api/v1/research/start-sync`) because:
|
||||||
|
|
||||||
Failures throw explicitly (0 feeds or 0 articles) — the runner catches and injects a "research failed" `ResolvedInput` with the error message so the planner doesn't hallucinate URLs.
|
Failures throw explicitly (0 feeds or 0 articles) — the runner catches and injects a "research failed" `ResolvedInput` with the error message so the planner doesn't hallucinate URLs.
|
||||||
|
|
||||||
|
#### Server-Side Research (mana-ai, ab v0.6)
|
||||||
|
|
||||||
|
The `mana-ai` background runner mirrors the client-side research pre-step. `NewsResearchClient` (`services/mana-ai/src/planner/news-research-client.ts`) calls `mana-api`'s `POST /api/v1/news-research/discover` + `/search` directly over the Docker network (`MANA_API_URL`). The same `RESEARCH_TRIGGER` regex is used; when it matches, results are injected as `ResolvedInput { id: '__web-research__' }` before the planner prompt is built.
|
||||||
|
|
||||||
|
Key differences from the client-side path:
|
||||||
|
- No SvelteKit context — pure HTTP fetch.
|
||||||
|
- 15s timeout on discover, 30s on search (tighter than client because the tick has a 60s cadence).
|
||||||
|
- Graceful null on any failure — the planner just runs without research context; tick doesn't crash.
|
||||||
|
- No `discoverByQuery` / `searchFeeds` module imports — the client ships those from `@mana/shared-rss`; the server calls the API endpoints which wrap the same logic.
|
||||||
|
|
||||||
|
This makes the Recherche-Agent and Today-Agent fully autonomous (no browser tab required). `research_news` is also registered as a proposable tool so the planner can explicitly request additional research as a PlanStep.
|
||||||
|
|
||||||
### 23.3 Kontext Auto-Inject
|
### 23.3 Kontext Auto-Inject
|
||||||
|
|
||||||
The user's `kontextDoc` singleton is automatically appended to every planner call as a standing-context `ResolvedInput`, unless the mission already links it as an explicit input. Decrypted client-side only — the server-side mana-ai runner skips this (encryption barrier; needs a Key-Grant for server access).
|
The user's `kontextDoc` singleton is automatically appended to every planner call as a standing-context `ResolvedInput`, unless the mission already links it as an explicit input. Decrypted client-side only — the server-side mana-ai runner skips this (encryption barrier; needs a Key-Grant for server access).
|
||||||
|
|
|
||||||
|
|
@ -33,12 +33,13 @@ each one laying foundations the next one relies on:
|
||||||
| Plan | Status | Scope |
|
| Plan | Status | Scope |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| [`ai-mission-key-grant.md`](./ai-mission-key-grant.md) | ✅ Shipped | Per-mission RSA-wrapped key grant so `mana-ai` can decrypt allowlisted encrypted records when user opts in. |
|
| [`ai-mission-key-grant.md`](./ai-mission-key-grant.md) | ✅ Shipped | Per-mission RSA-wrapped key grant so `mana-ai` can decrypt allowlisted encrypted records when user opts in. |
|
||||||
| [`multi-agent-workbench.md`](./multi-agent-workbench.md) | ✅ Shipped | Identity-aware Actor + named AI agents owning missions + per-agent policy + scene lens. |
|
| [`multi-agent-workbench.md`](./multi-agent-workbench.md) | ✅ Shipped | Identity-aware Actor + named AI agents owning missions + per-agent policy + scene lens. 28 tools across 11 modules including server-side web-research. |
|
||||||
|
| [`workbench-templates.md`](./workbench-templates.md) | ✅ T1 Shipped | Generalised templates: 3 agent-templates + 3 non-AI workbench starter-kits. Seed-handler registry for per-module data seeding. |
|
||||||
| [`team-workbench.md`](./team-workbench.md) | 📝 Forward-looking | TeamSpace with membership, team-encrypted records, admin lens on team members. Reuses Actor.principalId + key-wrapping patterns from the two above. |
|
| [`team-workbench.md`](./team-workbench.md) | 📝 Forward-looking | TeamSpace with membership, team-encrypted records, admin lens on team members. Reuses Actor.principalId + key-wrapping patterns from the two above. |
|
||||||
|
|
||||||
Cross-references:
|
Cross-references:
|
||||||
|
|
||||||
- Architecture narrative: [`docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md`](../architecture/COMPANION_BRAIN_ARCHITECTURE.md) §20 (AI Workbench base), §21 (Mission Grants), §22 (Multi-Agent)
|
- Architecture narrative: [`docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md`](../architecture/COMPANION_BRAIN_ARCHITECTURE.md) §20 (AI Workbench base), §21 (Mission Grants), §22 (Multi-Agent), §23 (Reasoning Loop + Research + Debug)
|
||||||
- Non-plan ideas backlog: [`docs/future/AI_AGENTS_IDEAS.md`](../future/AI_AGENTS_IDEAS.md)
|
- Non-plan ideas backlog: [`docs/future/AI_AGENTS_IDEAS.md`](../future/AI_AGENTS_IDEAS.md)
|
||||||
- Service-internal notes: [`services/mana-ai/CLAUDE.md`](../../services/mana-ai/CLAUDE.md)
|
- Service-internal notes: [`services/mana-ai/CLAUDE.md`](../../services/mana-ai/CLAUDE.md)
|
||||||
- Webapp-internal notes: [`apps/mana/CLAUDE.md`](../../apps/mana/CLAUDE.md) → "AI Workbench" section
|
- Webapp-internal notes: [`apps/mana/CLAUDE.md`](../../apps/mana/CLAUDE.md) → "AI Workbench" section
|
||||||
|
|
|
||||||
|
|
@ -75,6 +75,17 @@ Der Runner wird agent-bewusst — Missionen gehoeren einem benannten Agent, Poli
|
||||||
- [x] `filterToolsByAgentPolicy` schneidet `deny`-Tools raus bevor der Planner sie sieht.
|
- [x] `filterToolsByAgentPolicy` schneidet `deny`-Tools raus bevor der Planner sie sieht.
|
||||||
- [x] Metrik `mana_ai_agent_decisions_total{decision}`.
|
- [x] Metrik `mana_ai_agent_decisions_total{decision}`.
|
||||||
|
|
||||||
|
## Status: v0.6 (Server-side Web-Research + erweiterte Tools)
|
||||||
|
|
||||||
|
Der Runner kann jetzt vor dem Planner-Call eigenstaendig Web-Recherche ausfuehren (ohne Browser) und hat Zugriff auf 28 Tools ueber 11 Module.
|
||||||
|
|
||||||
|
- [x] `NewsResearchClient` (`planner/news-research-client.ts`) — HTTP-Client fuer `mana-api`'s `/api/v1/news-research/discover` + `/search`. Timeouts 15s/30s, graceful-null bei Fehler.
|
||||||
|
- [x] Pre-Planning-Research-Step in `cron/tick.ts` — bei Mission-Objectives mit Research-Keywords (`recherchier|research|news|today|historisch|...`) wird automatisch vor dem Planner-Call RSS-Discovery + Search ausgefuehrt. Ergebnisse als `ResolvedInput` mit `id='__web-research__'` injiziert.
|
||||||
|
- [x] `config.manaApiUrl` + Docker-Compose-Wiring (`MANA_API_URL: http://mana-api:3060`, `depends_on: mana-api`).
|
||||||
|
- [x] 28 Tools ueber 11 Module (17 propose, 11 auto):
|
||||||
|
- Propose: `create_task`, `complete_task`, `complete_tasks_by_title`, `create_event`, `create_note`, `update_note`, `append_to_note`, `add_tag_to_note`, `create_place`, `visit_place`, `undo_drink`, `save_news_article`, `create_journal_entry`, `create_habit`, `log_habit`, `research_news`, `create_contact`
|
||||||
|
- Auto: `get_task_stats`, `list_tasks`, `list_notes`, `get_todays_events`, `get_drink_progress`, `log_drink`, `nutrition_summary`, `log_meal`, `get_places`, `location_log`, `get_habits`, `get_contacts`
|
||||||
|
|
||||||
## Port: 3067
|
## Port: 3067
|
||||||
|
|
||||||
## Tech Stack
|
## Tech Stack
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue