diff --git a/apps/mana/CLAUDE.md b/apps/mana/CLAUDE.md index b4526115d..43fe25efd 100644 --- a/apps/mana/CLAUDE.md +++ b/apps/mana/CLAUDE.md @@ -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. - **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 diff --git a/docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md b/docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md index 4dc31829f..efe0bed27 100644 --- a/docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md +++ b/docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md @@ -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. +#### 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 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). diff --git a/docs/plans/README.md b/docs/plans/README.md index 4664e83f9..964c672e0 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -33,12 +33,13 @@ each one laying foundations the next one relies on: | 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. | -| [`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. | 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) - 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 diff --git a/services/mana-ai/CLAUDE.md b/services/mana-ai/CLAUDE.md index 05c0d03fc..6b9eb7dbf 100644 --- a/services/mana-ai/CLAUDE.md +++ b/services/mana-ai/CLAUDE.md @@ -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] 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 ## Tech Stack