feat: add api key auth, devii agent, openai gateway, and admin service management

This commit introduces a comprehensive set of new features including API key authentication with CLI management commands (get, reset, backfill), a Devii agentic assistant with WebSocket terminal and session bootstrap, an OpenAI-compatible LLM gateway service, and an admin service management panel. It also adds Playwright browser automation for bot support, configures internal gateway URLs, refactors content editing/deletion to support JSON API responses, and updates documentation across AGENTS.md, README.md, and the developer docs site.
2026-06-08 15:38:33 +00:00
parent 921e382cbc
commit e0535bb7c5
270 changed files with 54408 additions and 541 deletions
@@ -0,0 +1,101 @@
+# retoor <retoor@molodetz.nl>
+
+from __future__ import annotations
+
+from ..actions.spec import Action, Param
+
+
+def arg(name: str, description: str, required: bool = False, kind: str = "string") -> Param:
+    return Param(name=name, location="body", description=description, required=required, type=kind)
+
+
+AGENTIC_ACTIONS: tuple[Action, ...] = (
+    Action(
+        name="plan",
+        method="LOCAL",
+        path="",
+        summary="Record the structured execution plan for the current request",
+        description="Must be the very first tool call when a request requires any tool use.",
+        handler="agentic",
+        requires_auth=False,
+        params=(
+            arg("goal", "One-line restatement of the user's goal.", required=True),
+            arg("steps", "Ordered list of step objects, each with id, action, depends_on.", required=True, kind="array"),
+            arg("success_criteria", "Concrete criteria for declaring the task complete.", required=True),
+            arg("confidence", "Self-estimate of plan correctness from 0.0 to 1.0.", kind="number"),
+        ),
+    ),
+    Action(
+        name="reflect",
+        method="LOCAL",
+        path="",
+        summary="Record a reflection and persist it as a reusable lesson for future requests",
+        description="Call after any tool error and at the end of a non-trivial task to learn from it.",
+        handler="agentic",
+        requires_auth=False,
+        params=(
+            arg("observation", "What was observed: the failure mode or notable outcome.", required=True),
+            arg("conclusion", "Diagnosis or interpretation of the observation.", required=True),
+            arg("next_action", "The chosen next step or the rule to apply in future.", required=True),
+            arg("tags", "Optional comma-separated keywords to aid later recall."),
+        ),
+    ),
+    Action(
+        name="recall",
+        method="LOCAL",
+        path="",
+        summary="Retrieve relevant lessons learned from past requests",
+        description="Search the persistent lesson memory for guidance before acting on unfamiliar work.",
+        handler="agentic",
+        requires_auth=False,
+        params=(
+            arg("query", "Natural-language or keyword query describing the current situation.", required=True),
+            arg("k", "Number of lessons to return.", kind="integer"),
+        ),
+    ),
+    Action(
+        name="forget_lessons",
+        method="LOCAL",
+        path="",
+        summary="Permanently delete learned lessons from your private memory",
+        description=(
+            "Removes lessons you previously stored with reflect(). With a query, only matching "
+            "lessons are deleted; with no query, all of them are. Use this when the user asks you "
+            "to forget something. Your lesson memory is private to this account or guest session."
+        ),
+        handler="agentic",
+        requires_auth=False,
+        params=(
+            arg("query", "Optional topic/keywords; only matching lessons are forgotten. Omit to forget everything."),
+        ),
+    ),
+    Action(
+        name="verify",
+        method="LOCAL",
+        path="",
+        summary="Confirm that a change took effect, satisfying the verification gate",
+        description=(
+            "After mutating actions (create, edit, delete, vote, follow, admin changes), confirm "
+            "the result, then call this with a summary of what you confirmed."
+        ),
+        handler="agentic",
+        requires_auth=False,
+        params=(
+            arg("summary", "What was confirmed and how.", required=True),
+            arg("confirmed", "Whether the change was confirmed successful.", kind="boolean"),
+        ),
+    ),
+    Action(
+        name="delegate",
+        method="LOCAL",
+        path="",
+        summary="Spawn a focused sub-agent to complete a self-contained sub-task in isolation",
+        description="The sub-agent runs its own plan/act/verify loop and returns a concise result.",
+        handler="agentic",
+        requires_auth=False,
+        params=(
+            arg("task", "Clear, scoped task description for the sub-agent.", required=True),
+            arg("allowed_tools", "Optional list of tool names the sub-agent may use.", kind="array"),
+        ),
+    ),
+)