075 Agents A10eaef8

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).
• Single endpoint: POST /api/query.
• Auth: requires X-API-KEY header. Token defaults to api.master_token from configs/app.json (default: msk-strong-password).
• Orchestration: calls meeseeks_core.task_master.orchestrate_session(...) with auto_approve and a shared SessionStore.
• Sessions: supports session_id, session_tag, and fork_from (tag or id). Tags are resolved via SessionStore.

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 orchestrate_session 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.