075 Agents 0b1af3fc

# Meeseeks API - Project Guidance

Scope: this file applies to the `apps/meeseeks_api/` package. It captures runtime behavior, hidden dependencies, and testing notes so changes stay safe and predictable.

## Runtime flow (what actually happens)
- Entry point: `apps/meeseeks_api/src/meeseeks_api/backend.py` (HTTP API framework).
- Session endpoints:
  - `POST /api/sessions` create session
  - `GET /api/sessions` list sessions
  - `POST /api/sessions/{session_id}/query` enqueue run or core command
  - `GET /api/sessions/{session_id}/events?after=...` poll events
  - `POST /api/query` synchronous endpoint (simple/CLI-compatible)
  - `GET /api/tools` list tool registry entries
  - `GET /api/notifications` list notifications
  - `POST /api/notifications/dismiss` dismiss notifications
  - `POST /api/notifications/clear` clear notifications
  - `POST /api/sessions/{session_id}/attachments` upload attachments
  - `POST /api/sessions/{session_id}/share` create share link
  - `POST /api/sessions/{session_id}/export` export session payload
  - `GET /api/share/{token}` fetch shared session data
- Auth: requires `X-API-KEY` header. Token defaults to `api.master_token` from `configs/app.json` (default: `msk-strong-password`).
- Orchestration: uses `meeseeks_core.session_runtime.SessionRuntime` to run sync/async sessions.
- Core commands: `/compact`, `/status`, `/terminate` (shared runtime).
- Sessions: supports `session_id`, `session_tag`, and `fork_from` (tag or id). Tags are resolved via `SessionStore`.
- Event payloads: `action_plan` steps are `{title, description}`; tool events use `tool_id`, `operation`, `tool_input`.

## Hidden dependencies / assumptions
- Uses core logging (`meeseeks_core.common.get_logger`); log level controlled by `runtime.log_level`.
- Relies on core LLM config (`llm.api_base`, `llm.api_key`, `llm.default_model`, `llm.action_plan_model`).
- No rate limiting or auth hardening beyond the header token.

## Pitfalls / gotchas
- `api.master_token` default is insecure; production should override it in `configs/app.json`.
- No heartbeat or health endpoint; external deployments must handle liveness checks.
- The API returns the whole `TaskQueue` including action steps; ensure tool results are safe to expose.
- Treat language models as black-box APIs with non-deterministic output; avoid anthropomorphic language in docs/changes.

## Testing guidance
- `apps/meeseeks_api/tests` mock `SessionRuntime.run_sync` and focus on response schema.
- Avoid mocking too much of core: keep at least one integration test that exercises `SessionStore` behavior.

## Cross-project insights (fast decision help)
- Explicit tool allowlists and permission gates reduce unsafe actions; keep API calls explicit and auditable.
- Clear turn boundaries help keep outputs stable; avoid mixing raw tool output with the final response.
- Keep the API surface small and obvious; avoid hidden behaviors.