Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

17.5 KB
Raw Blame
"""New ecosystem capabilities must be decided FOR or AGAINST the MCP surface.

The failure this prevents is drift, not a crash. Somebody adds
`POST /api/society/agents/{id}/vacation`, the app grows a button, and every MCP
client silently stays a version behind — nobody notices, because nothing breaks.
Six months later the surface is a partial mirror nobody trusts.

So the society's REST surface is enumerated here and every route must be
accounted for: either it has a tool, or it is listed as deliberately not
exposed WITH a reason. A new route fails this test until someone makes that
call. Answering "not exposed, because …" takes one line — the point is that the
decision is made, not that everything is exposed.
"""

from __future__ import annotations

from typing import Final

from dodaios.mcp.agents import TOOLS
from dodaios.ui.web.society_browser_routes import router as browser_router
from dodaios.ui.web.society_routes import router as society_router

#: REST route -> the MCP tool that covers it.
COVERED: Final[dict[str, str]] = {
    "GET /api/society/agents": "agents_list",
    "POST /api/society/agents": "agent_create",
    "GET /api/society/agents/{agent_id}": "agent_get",
    "POST /api/society/agents/{agent_id}/message": "agent_message",
    "POST /api/society/agents/{agent_id}/assign": "agent_assign",
    "GET /api/society/agents/{agent_id}/inbox": "agent_inbox",
    "GET /api/society/events": "board_events",
    "GET /api/society/capabilities": "capabilities_list",
    "GET /api/society/rooms": "rooms_list",
    "POST /api/society/rooms": "room_open",
    "POST /api/society/rooms/{room_id}/say": "room_say",
    "POST /api/society/rooms/{room_id}/settle": "room_settle",
    "GET /api/society/approvals": "approvals_list",
    "POST /api/society/approvals/{approval_id}/resolve": "approval_resolve",
    "GET /api/society/quests": "quests_list",
    "POST /api/society/quests": "quest_post",
    "GET /api/society/quests/{quest_id}": "quest_get",
    "POST /api/society/quests/{quest_id}/cancel": "quest_cancel",
    "POST /api/society/quests/{quest_id}/retry": "quest_retry",
    "GET /api/society/status": "ecosystem_status",
    "POST /api/society/kill-switch/release": "kill_switch",
    "POST /api/society/kill-switch": "kill_switch",
}

#: REST route -> why an MCP client does not get it. Each line is a decision.
WITHHELD: Final[dict[str, str]] = {
    "GET /api/society/sandbox": (
        "Docker readiness belongs to the owner's local execution settings, "
        "not the remote MCP surface"
    ),
    "POST /api/society/sandbox/prepare": (
        "downloading a local container runtime is an explicit owner action in the app or CLI"
    ),
    "GET /api/society/agents/{agent_id}/sandbox/files": (
        "sandbox artifacts are browsed by the owner; remote MCP clients do not get raw file access"
    ),
    "GET /api/society/agents/{agent_id}/sandbox/file": (
        "binary artifact downloads belong to the owner-facing app and REST/CLI surface"
    ),
    "GET /api/society/designs": (
        "the saved companion-design library belongs to the owner's appearance "
        "editor; a remote client changes an agent's look through its profile"
    ),
    "POST /api/society/designs": (
        "saving a companion design is an appearance-editor action for the owner"
    ),
    "DELETE /api/society/designs/{design_id}": (
        "deleting a saved companion design is an appearance-editor action for the owner"
    ),
    "GET /api/society/provider-prefs": (
        "which providers the agents may use is a settings page for the owner; "
        "a remote client already sees the effective seat on each agent"
    ),
    "PUT /api/society/provider-prefs": (
        "turning providers off for every agent is the owner's billing decision "
        "and is never handed to a remote client"
    ),
    "POST /api/society/agents/{agent_id}/browser/restart": (
        "native browser recovery is initiated by the owner in the browser panel; "
        "remote clients must not interrupt the person's manual browser session"
    ),
    "GET /api/society/agents/{agent_id}/template": (
        "the share draft is read in the owner's Share sheet; a remote client has "
        "ecosystem_export for the design of the whole team"
    ),
    "PUT /api/society/agents/{agent_id}/template": (
        "editing the public version of an agent is the owner's decision at their keyboard"
    ),
    "POST /api/society/agents/{agent_id}/template/publish": (
        "publishing goes out under the owner's GitHub name — never from a remote client"
    ),
    "POST /api/society/templates/install": (
        "installing a stranger's template is a consent decision made in the app, "
        "where the instructions are on screen first"
    ),
    "GET /api/society/starters": (
        "the starter gallery is the New-agent dialog's catalogue; MCP clients "
        "create agents through agent_create"
    ),
    "POST /api/society/starters/preview": (
        "the import preview exists so the owner reads a template on screen "
        "before anything is created"
    ),
    "POST /api/society/starters/install": (
        "creating from a starter or an imported template is the dialog's consent "
        "step, made in the app with the preview on screen"
    ),
    "PATCH /api/society/agents/{agent_id}": (
        "editing a roster row (model, ceiling, focus) is configuration the owner "
        "does at their own keyboard, not something a remote client should change"
    ),
    "DELETE /api/society/agents/{agent_id}": (
        "archiving a teammate is destructive and irreversible from outside"
    ),
    "GET /api/society/agents/{agent_id}/credentials": (
        "an agent's stored credentials are the owner's business, managed in the app only"
    ),
    "DELETE /api/society/agents/{agent_id}/credentials/{env}": (
        "deleting a stored credential breaks the agent's work and stays with the owner"
    ),
    "GET /api/society/agents/{agent_id}/logins": (
        "an agent's stored website logins are the owner's business, managed in the app only"
    ),
    "DELETE /api/society/agents/{agent_id}/logins/{key}": (
        "deleting a stored login breaks the agent's sign-in and stays with the owner"
    ),
    "POST /api/society/agents/{agent_id}/kill": (
        "kill_switch stops the whole house; killing ONE agent's runs needs the "
        "context of watching them, which a remote client does not have"
    ),
    "POST /api/society/agents/{agent_id}/model": (
        "provider/model choice spends the owner's subscription — theirs to make"
    ),
    "GET /api/society/proposals": (
        "configuration proposals are decided on the card in the agent's chat by the "
        "person who owns the agent; a remote client has no such card"
    ),
    "POST /api/society/proposals/{proposal_id}/resolve": (
        "confirming a proposal changes an agent's rules, routines or skills — the "
        "owner's decision at their own keyboard, never a remote client's"
    ),
    "GET /api/society/agents/{agent_id}/review-queue": (
        "the learning review queue is the owner's view in the agent's details pane"
    ),
    "POST /api/society/agents/{agent_id}/review/{item_id}/{decision}": (
        "approving or rejecting what an agent learned is the owner's decision, "
        "never a remote client's"
    ),
    "POST /api/society/onboarding/start": (
        "the one-time team offer is onboarding UI in the lead's chat, not an API verb"
    ),
    "GET /api/society/seeds": "starter-team proposals are onboarding UI, not an API verb",
    "POST /api/society/seeds/apply": (
        "onboarding, and it creates several agents at once — quest_post forges "
        "the one agent a job actually needs instead"
    ),
    "GET /api/society/providers": (
        "the provider/account picker is app UI; agent_get already reports the "
        "model an agent runs on"
    ),
    "GET /api/society/agents/{agent_id}/skills": (
        "agent_get already returns the skill list, so a second tool would only "
        "spend a client's tool budget"
    ),
    "POST /api/society/agents/{agent_id}/skills/{slug}/promote": (
        "promoting a learned skill into the global registry is a review step the "
        "owner does in the app, where they can read the skill first"
    ),
    "GET /api/society/browser/status": "browser install state is local setup, not ecosystem state",
    "POST /api/society/browser/install": "installs software on the machine — never from outside",
    "POST /api/society/browser/repair": "repairs host software; local owner setup",
    "POST /api/society/agents/{agent_id}/browser/cancel": (
        "local browser control belongs to the owner UI"
    ),
    "GET /api/society/agents/{agent_id}/browser/open": (
        "whether the owner UI may attach its live view; local process state"
    ),
    "POST /api/society/agents/{agent_id}/browser/session": (
        "prepares the host browser environment; owner UI, not an external agent command"
    ),
    "GET /api/society/agents/{agent_id}/browser": (
        "per-agent browser install state — local machine setup, like browser/status"
    ),
    "POST /api/society/agents/{agent_id}/browser/login": (
        "opens an interactive login window on the owner's screen; meaningless remotely"
    ),
    "POST /api/society/agents/{agent_id}/browser/login/done": (
        "the second half of the interactive login flow; useless without the window"
    ),
    "GET /api/society/agents/{agent_id}/routines": (
        "routines are scheduled spend; listing is harmless but pairs with creation, "
        "and neither belongs on a surface a client can drive unattended"
    ),
    "POST /api/society/agents/{agent_id}/routines": "creates recurring spend — owner-only",
    "POST /api/society/approvals": (
        "an MCP client asks for approval by USING a tool that needs one; it has no "
        "reason to park an action it invented"
    ),
    "POST /api/society/approvals/resurface": (
        "app-focus plumbing: it re-asks parked items when the window comes "
        "forward, which has no meaning for a remote client"
    ),
    "POST /api/society/agents/{agent_id}/chat": (
        "seats an agent's chat session without sending anything — a UI "
        "preparation step. agent_chat does it as part of talking"
    ),
    "GET /api/society/memory": (
        "the Memory House has its own surface; not part of this contract yet"
    ),
    "POST /api/society/memory/recall": (
        "recall reads an agent's private knowledge; the Memory House contract "
        "is not settled, and half a memory API is worse than none"
    ),
    "POST /api/society/memory/{knowledge_id}/promote": (
        "promoting private knowledge to shared is a privacy decision the owner "
        "makes after reading it — approvals_list surfaces it when an agent asks"
    ),
    "POST /api/society/memory/{knowledge_id}/dismiss": (
        "the other half of that review; it belongs with the reading, in the app"
    ),
    "GET /api/society/memory/file": (
        "the Updating Memory editor reads one society file for the owner to "
        "review the red/green change; a remote client has no editor and "
        "recall already covers lookup"
    ),
    "GET /api/society/agents/{agent_id}/knowledge": (
        "lists an agent's private memory files for the owner; remote clients "
        "do not receive the agent notebook browsing surface"
    ),
    "GET /api/society/agents/{agent_id}/knowledge/file": (
        "reads a private agent memory file for the owner in the app; remote "
        "clients do not receive raw notebook contents"
    ),
    "PATCH /api/society/agents/{agent_id}/routines/{task_id}": (
        "editing a routine changes recurring spend; the owner does it on the "
        "routine card where the schedule is visible, not via a remote client"
    ),
    "POST /api/society/agents/{agent_id}/routines/{task_id}/operation": (
        "pausing, deleting or running a routine now changes recurring spend; "
        "the owner does it on the routine card, not via a remote client"
    ),
    "GET /api/society/agents/{agent_id}/routines/{task_id}/runs": (
        "a routine's run history is the owner's read-out on the routine card; "
        "a remote client reads results in the agent's own chat"
    ),
    "GET /api/society/agents/{agent_id}/routines-activity": (
        "newest run per routine and the away-parking banner feed the routine "
        "list in the app; nothing a remote client acts on"
    ),
    "POST /api/society/agents/{agent_id}/routines-seen": (
        "records that the owner looked at routine results in the app; a remote "
        "client reporting it would defeat away-parking"
    ),
    "POST /api/society/agents/{agent_id}/routines-parking": (
        "answering the away-parking banner resumes recurring spend; the owner "
        "does it on the routine list, not via a remote client"
    ),
    "GET /api/society/routine-parking": "the away-parking window is an owner setting in the app",
    "PUT /api/society/routine-parking": "changing the away-parking window is an owner setting",
    "GET /api/society/agents/{agent_id}/conversations": (
        "lists the agent's chats with Jarvis and teammates for the owner's "
        "history rail in the app; a remote client messages agents directly"
    ),
    "GET /api/society/chat-groups": (
        "group chats are the owner's own chat layout in the app; a remote "
        "client addresses agents directly"
    ),
    "POST /api/society/chat-groups": "arranging the owner's group chats is app-only UI state",
    "PATCH /api/society/chat-groups/{group_id}": (
        "renaming or regrouping the owner's group chats is app-only UI state"
    ),
    "DELETE /api/society/chat-groups/{group_id}": (
        "ungrouping the owner's chats is app-only UI state"
    ),
    "GET /api/society/chat-groups/{group_id}/meeting": (
        "a group meeting's transcript belongs to the owner's group chat in the "
        "app; a remote client reads each agent's own chat"
    ),
    "POST /api/society/chat-groups/{group_id}/meeting": (
        "a meeting round bills a turn on every member's seat and starts only "
        "from the owner's explicit message in the app"
    ),
    "POST /api/society/chat-groups/{group_id}/meeting/stop": (
        "stops the owner's meeting round, which only the app can start"
    ),
    "GET /api/society/chat-groups/{group_id}/team": (
        "the team board (lead, mission, goals, tasks) is the owner's view of a "
        "group in the app; a remote client reads each agent's own chat"
    ),
    "PUT /api/society/chat-groups/{group_id}/lead": (
        "naming a team's lead changes an agent's tier and is the owner's "
        "decision in the app"
    ),
    "POST /api/society/chat-groups/{group_id}/lead": (
        "creates a new agent as the team's lead; staffing a team is the "
        "owner's decision in the app"
    ),
    "PUT /api/society/chat-groups/{group_id}/mission": (
        "the team's standing mission is the owner's own instruction, set in the app"
    ),
    "PUT /api/society/chat-groups/{group_id}/checkin": (
        "switches on recurring unprompted turns on the lead's seat; only the "
        "owner starts work that bills by itself"
    ),
    "POST /api/society/chat-groups/{group_id}/goals": (
        "a remote client gives a team a goal by assigning work to its lead "
        "(agent_assign), which becomes the team's goal"
    ),
    "POST /api/society/chat-groups/{group_id}/goals/{goal_id}/message": (
        "answering the lead's question on a goal is the owner's reply on the "
        "team board in the app"
    ),
    "POST /api/society/chat-groups/{group_id}/goals/{goal_id}/resume": (
        "continuing a paused goal restarts paid turns and is the owner's "
        "decision on the team board"
    ),
    "POST /api/society/chat-groups/{group_id}/goals/{goal_id}/cancel": (
        "stopping a team's goal is the owner's decision on the team board in the app"
    ),
}


def _routes() -> set[str]:
    """Every society REST route as ``METHOD /path``."""
    found: set[str] = set()
    for route in (*society_router.routes, *browser_router.routes):
        path = getattr(route, "path", None)
        methods = getattr(route, "methods", None) or set()
        if not path:
            continue
        for method in methods:
            if method in ("HEAD", "OPTIONS"):
                continue
            found.add(f"{method} {path}")
    return found


def test_every_society_route_is_decided() -> None:
    """A new route is neither exposed nor withheld until somebody says which."""
    routes = _routes()
    decided = set(COVERED) | set(WITHHELD)
    undecided = routes - decided
    assert not undecided, (
        "These society routes are new to the MCP surface and nobody has decided "
        f"about them yet: {sorted(undecided)}.\n"
        "Add a tool in dodaios/mcp/agents/tools.py and list it in COVERED, or list "
        "it in WITHHELD with one line saying why a remote client does not get it."
    )


def test_no_stale_decisions() -> None:
    """A route that disappeared must not leave a decision behind."""
    routes = _routes()
    stale = (set(COVERED) | set(WITHHELD)) - routes
    assert not stale, (
        f"These routes no longer exist but are still listed here: {sorted(stale)}. "
        "Drop them from COVERED / WITHHELD."
    )


def test_covered_routes_name_real_tools() -> None:
    published = {t.name for t in TOOLS}
    for route, tool in COVERED.items():
        assert tool in published, f"{route} claims tool {tool!r}, which does not exist"


def test_every_withheld_route_states_a_reason() -> None:
    for route, reason in WITHHELD.items():
        assert len(reason) > 25, f"{route} is withheld without a real reason"