till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-15 01:21:09 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
managarten/docs/plans
History
Till JS f07eae3c01 feat(personas): M3.b-d — tick loop + Claude Agent SDK + persistence (real) 
Previous commit 38dc80654 carries this M3 title but its payload is an
unrelated apps/api/picture change — shared-.git-index race with a
parallel session (see feedback_git_workflow.md). This commit holds the
actual M3.b/c/d code. Leaving the misnamed commit for the user to
re-attribute / revert as they prefer.

Closes the M3 loop from docs/plans/mana-mcp-and-personas.md. The
runner picks up due personas, drives each through Claude + MCP for
one simulated turn, collects actions + ratings, persists through
service-key internal endpoints in mana-auth.

Internal endpoints (mana-auth, service-key-gated)

- GET  /api/v1/internal/personas/due
    Returns personas whose tickCadence + lastActiveAt say they're
    due. Rules: hourly > 1h, daily > 24h, weekdays > 24h mon-fri.
    NULLS FIRST so never-run personas go ahead of stale ones.

- POST /api/v1/internal/personas/:id/actions
    Batch ≤ 500. Row ids are deterministic
    `${tickId}-${i}-${toolName}` + ON CONFLICT DO NOTHING so the
    runner can retry a tick without doubling audit rows. Also
    bumps personas.last_active_at so the next /due call sees it.

- POST /api/v1/internal/personas/:id/feedback
    Batch ≤ 100. Row id is `${tickId}-${module}` — natural key is
    one rating per module per tick.

Runner tick pipeline (services/mana-persona-runner/src/runner/)

- claude-session.ts
    Two phases per tick. runMainTurn feeds the persona's system
    prompt + a German "simulate a day" user prompt to Claude Agent
    SDK's query(), with mana-mcp wired in as a streamable-HTTP MCP
    server. We iterate the returned AsyncGenerator and extract
    tool_use blocks into ActionRows; a tool_result with
    is_error=true flips the most recent action. runRatingTurn is a
    fresh query() with tools:[] asking Claude in character to rate
    each used module 1-5 as strict JSON. We parse with tolerance
    for whitespace / fences. Unparseable output becomes a synthetic
    '__parse' feedback row so operators see the failure.

- tick.ts
    Orchestrator. Skips when config.paused. Fetches /due, processes
    in batches of config.concurrency via Promise.allSettled so a
    single persona failure never kills the batch. Returns
    {due, ranSuccessfully, failed[], durationMs}.

- types.ts
    ActionRow + FeedbackRow shapes shared between claude-session
    and the internal client.

Runner bootstrap (src/index.ts)

- setInterval(config.tickIntervalMs) starts the tick loop on boot.
  tickInFlight guards against overlap when Claude latency >
  interval. If MANA_SERVICE_KEY or ANTHROPIC_API_KEY is missing,
  loop is disabled with a warn line — /health + /diag/login still
  work.
- POST /diag/tick (dev-only) fires one tick on demand, returns
  the result. Avoids waiting a full interval during testing.
- Graceful SIGTERM/SIGINT shutdown clears the interval.

Client

- clients/mana-auth-internal.ts
    X-Service-Key client for the three endpoints above.
    Constructor throws on empty serviceKey — fail loud.

Boot smoke verified: /health returns ok, /diag/tick 500s with
descriptive messages when keys absent. Warning lines on boot when
keys are missing. Type-check green across mana-auth, tool-registry,
mcp, persona-runner.

M3 exit gate is the end-to-end smoke recipe (docker up → db:push →
seed:personas → diag/tick → psql) documented in
services/mana-persona-runner/CLAUDE.md.

M2.d (cross-space family/team memberships) still deferred.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 14:18:31 +02:00
..
agent-loop-improvements-m1.md feat(agent-loop): M1 — policy gate + reminder channel + parallel reads 2026-04-23 13:56:40 +02:00
ai-mission-key-grant.md feat(ai): Mission Grant rollout gating — flag, alerts, runbook, user docs 2026-04-15 14:02:47 +02:00
articles-homepage.md feat(articles): M9 workbench homepage — 4-tab shell + QuickAdd + StatsView 2026-04-22 17:50:38 +02:00
articles-module.md feat(articles): M8 highlights view + stats + dashboard widget 2026-04-22 14:12:18 +02:00
broadcast-module.md docs(broadcast): plan newsletter / broadcast module 2026-04-20 19:32:53 +02:00
data-export-v2.md feat(backup): client-driven v2 snapshot export, drop server-side backup 2026-04-22 18:46:29 +02:00
event-discovery.md feat(events): add Event Discovery — Phase 1 + 2 2026-04-18 15:30:46 +02:00
invoices-module.md docs(invoices): mark all milestones done, list Phase-2/3 open items 2026-04-20 18:23:02 +02:00
library-module.md feat(library): M3 — progress tracking (pages, episodes, issues) + restart 2026-04-17 13:17:22 +02:00
mail-module-plan.md docs(mail): add TODO checklist for remaining Phase 1-4 work 2026-04-13 20:46:00 +02:00
mana-mcp-and-personas.md feat(personas): M3.b-d — tick loop + Claude Agent SDK + persistence (real) 2026-04-23 14:18:31 +02:00
mana-research-service.md feat(research): Phase 3a — 4 sync research agents 2026-04-17 15:06:12 +02:00
me-images-and-reference-generation.md feat(profile): UI for me-images management at /profile/me-images (M2) 2026-04-23 14:01:40 +02:00
multi-agent-workbench.md docs: flesh out Multi-Agent plan shipping log + Team Workbench forward plan 2026-04-15 22:17:04 +02:00
news-research-module.md docs: flesh out Multi-Agent plan shipping log + Team Workbench forward plan 2026-04-15 22:17:04 +02:00
per-space-vs-user-global-tags.md docs(plans): per-Space vs user-global tags — decision deferred 2026-04-22 15:32:15 +02:00
planner-function-calling.md docs(plans): mark shared-llm tool-call integration as deferred 2026-04-20 18:36:07 +02:00
README.md docs: update tool coverage table + server-side research + templates 2026-04-16 12:35:40 +02:00
scene-scope-empty-state.md docs(workbench): plan for scene-scope empty state 2026-04-18 16:23:13 +02:00
shared-space-smoketest.md feat(spaces): end-to-end shared-space sync (membership lookup + plaintext) 2026-04-20 20:46:53 +02:00
social-relay-module.md feat(spaces): add space types + module allowlist as multi-tenancy foundation 2026-04-20 15:57:57 +02:00
space-scoped-data-model.md docs(plans): point at-rest-sweep row at the restored commit 2026-04-22 22:43:19 +02:00
spaces-foundation.md feat(spaces): migrate calendar module to scoped-db wrapper (pilot) 2026-04-20 16:42:10 +02:00
team-workbench.md docs: flesh out Multi-Agent plan shipping log + Team Workbench forward plan 2026-04-15 22:17:04 +02:00
tipps-module.md Create tipps-module.md 2026-04-22 14:21:57 +02:00
website-builder.md feat(webapp): wire isParallelSafe in Companion chat + Mission runner 2026-04-23 14:11:24 +02:00
workbench-cards-migration.md docs(plans): revise workbench-cards plan for cards-for-workflows rule 2026-04-22 15:05:48 +02:00
workbench-templates.md feat(templates): generalise to WorkbenchTemplate + ship Calmness pilot (T1) 2026-04-16 01:07:41 +02:00

README.md

Plans

Design + rollout plans, grouped by topic. Plans are long-form docs with baked-in decisions, phasing, open questions, and (when shipped) a history section with commit refs.

AI / Workbench roadmap

The Mana AI Workbench has evolved in three successive planned waves — each one laying foundations the next one relies on:

  User hat einen Companion (v0 — shipped before these docs)
        │
        ▼
  AI Missions + Proposals + Policy + Revert
        │
        ▼
  Mission Key-Grants  ←  ai-mission-key-grant.md  ✅
    (encrypted inputs decryptable by the server runner)
        │
        ▼
  Multi-Agent Workbench  ←  multi-agent-workbench.md  ✅
    (named agents, per-agent policy/memory/budget,
     identity-aware Actor, scene→agent lens)
        │
        ▼
  Team Workbench  ←  team-workbench.md  📝 (not started)
    (multi-user + shared AI context,
     admin lens on team members)
Plan Status Scope
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 ✅ 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 ✅ T1 Shipped Generalised templates: 3 agent-templates + 3 non-AI workbench starter-kits. Seed-handler registry for per-module data seeding.
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:

Other plans

Plan Topic
mail-module-plan.md Mail module — IMAP/SMTP integration
news-research-module.md News + research pipeline