blindxfish/devplacepy
1
0
Fork 0
forked from retoor/devplacepy
Code Pull Requests Activity

feat: add /stop and /reset chat commands and bots internals docs section

Browse Source 
Add two new chat commands (`/stop` and `/reset`) to the Devii WebSocket handler, enabling users to stop or reset a session via text input. Introduce a new "Bots internals" documentation section with six prose pages covering architecture, personas, content generation, engagement, realism, and configuration for the autonomous bot fleet. Extend the bot service with article scoring, category picking, configurable pause/break timing, and a `gist_min_lines` parameter for LLM client initialization.
This commit is contained in:
retoor
2026-06-11 12:06:17 +00:00
parent 3540bc8fa6
commit 5488008216
37 changed files with 2576 additions and 340 deletions
Download Patch File Download Diff File Expand all files Collapse all files
devplacepy/services/devii/actions/behavior_actions.py
+33
View File
@@ -0,0 +1,33 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
from .spec import Action, Param
BEHAVIOR_ACTIONS: tuple[Action, ...] = (
Action(
name="update_behavior",
method="LOCAL",
path="",
summary="Update your own persistent '# TRUTH RULES AND BEHAVIOR' section",
description=(
"Records how the user wants you to behave into the '# TRUTH RULES AND BEHAVIOR' section at "
"the end of your system message, so the change persists across turns and restarts. Call it "
"when the user tells you to behave differently, says they expect different behavior, or you "
"upset them. The 'behavior' value is the FULL new content of that section: take the rules "
"currently shown there, apply the user's change (add, adjust, or remove a rule), and pass "
"the whole result so nothing already learned is lost unless they want it removed. Private "
"to this account (a guest's applies to the current session only)."
),
handler="behavior",
requires_auth=False,
params=(
Param(
name="behavior",
location="body",
description="The full new content of the '# TRUTH RULES AND BEHAVIOR' section.",
required=True,
),
),
),
)
devplacepy/services/devii/actions/client_actions.py
+208
View File
@@ -141,6 +141,214 @@ CLIENT_ACTIONS: tuple[Action, ...] = (
handler="client",
requires_auth=False,
),
Action(
name="discover_elements",
method="LOCAL",
path="",
summary="List the actionable elements on the user's screen in reading order, each with a stable ref, role, label, selector, and state",
description=(
CLIENT
+ " This is how you SEE the page before acting: it returns buttons, links, inputs, "
"textboxes, checkboxes, selects, tabs, and menu items in document (logical) order, each "
"with a `ref` (like e3) you can pass to click_element/fill_field/etc, plus its role, "
"accessible label, a robust CSS selector, current state (visible, enabled, checked, value), "
"and which form or modal it belongs to. Call this first, then act on the refs. Use `query` "
"to filter by label, `within` to scope to a region (a ref/selector, e.g. an open modal), and "
"`kind` to keep only one type."
),
handler="client",
requires_auth=False,
read_only=True,
params=(
arg("query", "Only return elements whose label contains this text (case-insensitive)."),
arg(
"within",
"Scope discovery to inside this element (a ref, CSS selector, or exact text), e.g. an open modal or form.",
),
arg(
"kind",
"Keep only one type: button, link, input, textbox, checkbox, radio, select, tab, or menuitem.",
),
arg("limit", "Maximum number of elements to return (default 40).", kind="integer"),
),
),
Action(
name="read_element",
method="LOCAL",
path="",
summary="Read one element in detail: text, value, attributes, state, position, and visibility",
description=CLIENT
+ " Use this to investigate a specific element you found with discover_elements, "
"or to confirm the result of an action (its value, whether it is checked, any error text near it).",
handler="client",
requires_auth=False,
read_only=True,
params=(
arg(
"target",
"The element to read: a ref (e3), a CSS selector, or its exact visible text.",
required=True,
),
),
),
Action(
name="click_element",
method="LOCAL",
path="",
summary="Click an element on the user's screen and report what changed",
description=(
CLIENT
+ " Scrolls the element into view, waits briefly for it to be visible and enabled, "
"dispatches a real click, and returns a delta (did the URL change, did a modal open or close, "
"any new toast or validation error, is the element still there). Prefer this over run_js for clicking. "
"Set `button` to 'right' for a context menu or 'double' for a double-click."
),
handler="client",
requires_auth=False,
params=(
arg(
"target",
"The element to click: a ref (e3), a CSS selector, or its exact visible text.",
required=True,
),
arg("button", "left (default), right, or double."),
),
),
Action(
name="fill_field",
method="LOCAL",
path="",
summary="Type a value into an input, textarea, contenteditable, or code editor and fire the right events",
description=(
CLIENT
+ " Sets the value through the native setter and dispatches input and change events, so "
"framework and validation handlers actually run (plain run_js value assignment does not). "
"Supports text inputs, textareas, contenteditable elements, and CodeMirror editors. "
"Returns the resulting value and any validation message shown near the field."
),
handler="client",
requires_auth=False,
params=(
arg(
"target",
"The field to fill: a ref (e3), a CSS selector, or its label/placeholder text.",
required=True,
),
arg("value", "The value to type into the field.", required=True),
),
),
Action(
name="set_control",
method="LOCAL",
path="",
summary="Toggle a checkbox or radio, or choose an option in a select",
description=CLIENT
+ " For a checkbox or radio pass `checked` true/false; for a select pass `option` "
"(matched against option value or visible label). Dispatches a change event.",
handler="client",
requires_auth=False,
params=(
arg(
"target",
"The control: a ref (e3), a CSS selector, or its label text.",
required=True,
),
arg("checked", "For a checkbox or radio: true to check, false to uncheck.", kind="boolean"),
arg("option", "For a select: the option value or visible label to choose."),
),
),
Action(
name="submit_form",
method="LOCAL",
path="",
summary="Optionally fill a form's fields, then submit it, and report what changed",
description=(
CLIENT
+ " Resolves the form that contains `target` (a ref/selector/text for the form, a field in it, "
"or its submit button). If `fields` is given (a map of field name/label to value) each is filled "
"first with the proper events, then the form is submitted by clicking its submit button (so app "
"handlers run) or calling requestSubmit. Returns a delta (URL change, modal open/close, toast, errors). "
"This is the primary tool for completing a mutation such as creating a post or saving a profile."
),
handler="client",
requires_auth=False,
params=(
arg(
"target",
"The form, one of its fields, or its submit button: a ref (e3), CSS selector, or exact text.",
required=True,
),
arg(
"fields",
"Optional map of field name or label to the value to fill before submitting.",
kind="object",
),
),
),
Action(
name="wait_for",
method="LOCAL",
path="",
summary="Wait until an element becomes visible, hidden, or contains text, before continuing",
description=(
CLIENT
+ " Polls the page until the condition holds or it times out, so sequences after a navigation, "
"click, or fetch do not race. `condition` is visible (default), hidden, or text_contains "
"(supply `text`). Returns whether it was satisfied and how long it waited."
),
handler="client",
requires_auth=False,
read_only=True,
params=(
arg(
"target",
"The element to wait on: a ref (e3), a CSS selector, or exact visible text.",
required=True,
),
arg("condition", "visible (default), hidden, or text_contains."),
arg("text", "For text_contains: the text the element should contain."),
arg("timeout_ms", "Maximum wait in milliseconds (default 8000, capped at 55000).", kind="integer"),
),
),
Action(
name="press_key",
method="LOCAL",
path="",
summary="Send a keypress to an element or the page (Enter, Escape, Tab, arrows, etc.)",
description=CLIENT
+ " Dispatches keydown/keypress/keyup for the named key to `target` (or the focused element "
"if omitted). Use Enter to submit, Escape to close a modal, Tab to move focus.",
handler="client",
requires_auth=False,
params=(
arg("key", "The key name: Enter, Escape, Tab, ArrowDown, a, etc.", required=True),
arg("target", "Optional element to send the key to: a ref (e3), selector, or exact text."),
),
),
Action(
name="run_sequence",
method="LOCAL",
path="",
summary="Run an ordered list of client steps in one round-trip, stopping on the first failure",
description=(
CLIENT
+ " Each step is an object with an `action` (click_element, fill_field, set_control, submit_form, "
"wait_for, press_key, scroll_to_element, read_element, discover_elements, highlight_element, show_toast) "
"and its arguments. Steps run in order with the page settling between them; execution stops at the first "
"error and returns every step's result plus the final page context. Use this to perform a whole UI flow "
"(open a modal, fill it, submit) reliably without a round-trip per step. run_js is not allowed inside a sequence."
),
handler="client",
requires_auth=False,
params=(
arg(
"steps",
"Ordered list of step objects, each with an `action` field and that action's arguments.",
required=True,
kind="array",
),
),
),
Action(
name="open_terminal",
method="LOCAL",
devplacepy/services/devii/agent.py
+20 -5
View File
@@ -49,13 +49,28 @@ SYSTEM_PROMPT = (
"data has the created resource's uid/slug/url. Always reuse those exact slugs/uids/urls for "
"follow-up calls instead of constructing them. "
"In the web terminal you can act on the user's own screen: get_page_context tells you where "
"they are and what they see; run_js executes JavaScript in their browser and returns a value; "
"highlight_element, show_toast, scroll_to_element and clear_highlights let you guide them with "
"live, on-screen tutorials; navigate_to and reload_page move or refresh their page (their "
"session and this conversation persist and reconnect automatically). Read the page context "
"before guiding, prefer the dedicated tools over raw run_js, and clear highlights when done. "
"they are and what they see; navigate_to and reload_page move or refresh their page; "
"highlight_element, show_toast, scroll_to_element and clear_highlights guide them with live, "
"on-screen tutorials; run_js executes JavaScript and returns a value. The session and this "
"conversation persist and reconnect automatically across navigation. "
"Confirm destructive actions with the user first. Schedule autonomous work with "
"create_task and related tools. All times are UTC.\n\n"
"DRIVING THE BROWSER (the reliable flow)\n"
"To act on the user's screen, follow this loop instead of guessing selectors or writing run_js. "
"(1) get_page_context to see where they are, the open modal, and visible toasts. "
"(2) discover_elements to list the actionable elements in reading order, each with a stable ref "
"(e3), role, label, selector, and state; pass `within` to scope to a modal/form, `query` to "
"filter by label, `kind` to keep one type. "
"(3) Act on the refs: click_element to click, fill_field to type (it fires the proper events, "
"unlike a raw value assignment), set_control for checkboxes/radios/selects, submit_form to fill "
"and submit a whole form in one call. Every act tool returns a delta (URL change, modal open or "
"close, new toast, validation error, element gone) - read it to confirm the result. "
"(4) wait_for after anything that triggers an async render (a modal opening, a fetch, a "
"navigation) so steps do not race; press_key for Enter/Escape/Tab. "
"(5) For a known multi-step flow, run_sequence executes the ordered steps in one round-trip and "
"stops at the first failure. "
"Prefer these structured tools over run_js; reach for run_js only for something none of them "
"cover. read_element inspects one element when investigating. Clear highlights when done.\n\n"
"AGGREGATES AND LARGE DATA\n"
"For any count, total, or 'how many' / 'how active' question, call site_analytics - it returns "
"member totals, active users over 24h/7d/30d, signups, content totals, and top authors in a "
devplacepy/services/devii/behavior/__init__.py
+6
View File
@@ -0,0 +1,6 @@
# retoor <retoor@molodetz.nl>
from .controller import BehaviorController
from .store import BehaviorStore
__all__ = ["BehaviorController", "BehaviorStore"]
devplacepy/services/devii/behavior/controller.py
+35
View File
@@ -0,0 +1,35 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
import json
import logging
from typing import Any
from devplacepy.services.devii.errors import ToolInputError
logger = logging.getLogger("devii.behavior")
class BehaviorController:
def __init__(self, store: Any) -> None:
self._store = store
async def dispatch(self, name: str, arguments: dict[str, Any]) -> str:
if name == "update_behavior":
return self._update(arguments)
raise ToolInputError(f"Unknown behavior tool: {name}")
def _update(self, arguments: dict[str, Any]) -> str:
behavior = arguments.get("behavior")
if behavior is None:
raise ToolInputError("'behavior' is required.")
self._store.set(str(behavior))
return json.dumps(
{
"status": "success",
"saved": True,
"note": "Updated your '# TRUTH RULES AND BEHAVIOR' section; it applies from your next turn.",
},
ensure_ascii=False,
)
devplacepy/services/devii/behavior/store.py
+49
View File
@@ -0,0 +1,49 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
import logging
from datetime import datetime, timezone
from typing import Any
logger = logging.getLogger("devii.behavior.store")
TABLE = "devii_behavior"
def _now_iso() -> str:
return datetime.now(timezone.utc).isoformat()
class BehaviorStore:
def __init__(self, db: Any, owner_kind: str, owner_id: str) -> None:
self._db = db
self._owner_kind = owner_kind
self._owner_id = owner_id
self._ensure_indexes()
def _ensure_indexes(self) -> None:
if TABLE not in self._db.tables:
return
self._db[TABLE].create_index(["owner_kind", "owner_id"])
@property
def _table(self) -> Any:
return self._db[TABLE]
@property
def _scope(self) -> dict[str, str]:
return {"owner_kind": self._owner_kind, "owner_id": self._owner_id}
def text(self) -> str:
if TABLE not in self._db.tables:
return ""
row = self._table.find_one(**self._scope)
return (row.get("behavior") or "") if row else ""
def set(self, behavior: str) -> None:
self._table.upsert(
{**self._scope, "behavior": behavior, "updated_at": _now_iso()},
["owner_kind", "owner_id"],
)
logger.info("Behavior updated owner=%s/%s", self._owner_kind, self._owner_id)
devplacepy/services/devii/client/controller.py
+19 -1
View File
@@ -21,12 +21,28 @@ EVAL_DISABLED = {
"status": "disabled",
"message": "JavaScript execution is disabled for Devii by the administrator.",
}
CONTROL_DISABLED = {
"status": "disabled",
"message": "Browser control is disabled for Devii by the administrator.",
}
CONTROL_ACTIONS = frozenset(
{
"click_element",
"fill_field",
"set_control",
"submit_form",
"press_key",
"run_sequence",
}
)
class ClientController:
def __init__(self, allow_eval: bool = True) -> None:
def __init__(self, allow_eval: bool = True, allow_control: bool = True) -> None:
self._request: Optional[RequestSink] = None
self._allow_eval = allow_eval
self._allow_control = allow_control
def bind(self, request: RequestSink) -> None:
self._request = request
@@ -43,6 +59,8 @@ class ClientController:
async def dispatch(self, name: str, arguments: dict[str, Any]) -> str:
if name == "run_js" and not self._allow_eval:
return json.dumps(EVAL_DISABLED, ensure_ascii=False)
if name in CONTROL_ACTIONS and not self._allow_control:
return json.dumps(CONTROL_DISABLED, ensure_ascii=False)
if self._request is None:
return json.dumps(UNAVAILABLE, ensure_ascii=False)
try:
devplacepy/services/devii/config.py
+5
View File
@@ -63,6 +63,7 @@ class Settings:
fetch_max_bytes: int
fetch_allow_private: bool
allow_eval: bool
browser_control: bool
rsearch_enabled: bool
rsearch_url: str
rsearch_timeout_seconds: float
@@ -136,6 +137,8 @@ def load_settings() -> Settings:
in ("1", "true", "yes", "on"),
allow_eval=os.environ.get("DEVII_ALLOW_EVAL", "1").lower()
in ("1", "true", "yes", "on"),
browser_control=os.environ.get("DEVII_BROWSER_CONTROL", "1").lower()
in ("1", "true", "yes", "on"),
rsearch_enabled=os.environ.get("DEVII_RSEARCH_ENABLED", "1").lower()
in ("1", "true", "yes", "on"),
rsearch_url=os.environ.get("DEVII_RSEARCH_URL", DEFAULT_RSEARCH_URL).rstrip(
@@ -162,6 +165,7 @@ FIELD_PRICE_CACHE_HIT = "devii_price_cache_hit"
FIELD_PRICE_CACHE_MISS = "devii_price_cache_miss"
FIELD_PRICE_OUTPUT = "devii_price_output"
FIELD_ALLOW_EVAL = "devii_allow_eval"
FIELD_BROWSER_CONTROL = "devii_browser_control"
FIELD_TIMEOUT = "devii_timeout"
FIELD_FETCH_TIMEOUT = "devii_fetch_timeout"
FIELD_RSEARCH_ENABLED = "devii_rsearch_enabled"
@@ -219,6 +223,7 @@ def build_settings(
fetch_max_bytes=DEFAULT_FETCH_MAX_BYTES,
fetch_allow_private=False,
allow_eval=bool(config.get(FIELD_ALLOW_EVAL, True)),
browser_control=bool(config.get(FIELD_BROWSER_CONTROL, True)),
rsearch_enabled=bool(config.get(FIELD_RSEARCH_ENABLED, True)),
rsearch_url=(config.get(FIELD_RSEARCH_URL) or DEFAULT_RSEARCH_URL).rstrip("/"),
rsearch_timeout_seconds=float(
devplacepy/services/devii/service.py
+10
View File
@@ -116,6 +116,16 @@ class DeviiService(BaseService):
"Other client tools (navigate, reload, highlight, toast, context) are unaffected.",
group="Agent",
),
ConfigField(
config.FIELD_BROWSER_CONTROL,
"Allow browser control",
type="bool",
default=True,
help="Let Devii drive the user's own browser with structured tools "
"(discover elements, click, fill, submit, wait, sequences). Independent of "
"raw JavaScript execution; read-only tools (context, discover, read) are unaffected.",
group="Agent",
),
ConfigField(
config.FIELD_USER_DAILY_USD,
"Max USD per user / 24h",
devplacepy/services/devii/session.py
+74 -7
View File
@@ -38,6 +38,32 @@ INTERNAL_PREFIXES = (
)
BUFFERED_TYPES = ("task", "error", "reply", "status")
BEHAVIOR_HEADER = "# TRUTH RULES AND BEHAVIOR"
def _repair_history(messages: list[dict[str, Any]]) -> None:
last_idx = None
for i in range(len(messages) - 1, -1, -1):
message = messages[i]
if message.get("role") == "assistant" and message.get("tool_calls"):
last_idx = i
break
if last_idx is None:
while messages and messages[-1].get("role") == "tool":
messages.pop()
return
declared = {
call.get("id")
for call in (messages[last_idx].get("tool_calls") or [])
if call.get("id")
}
answered = {
messages[j].get("tool_call_id")
for j in range(last_idx + 1, len(messages))
if messages[j].get("role") == "tool"
}
if not declared or not declared.issubset(answered):
del messages[last_idx:]
LOGIN_REQUEST = (
"Welcome to Devii. Ask me anything - I can generate clients and bots, search the docs, "
"fetch pages, and more. Sign in to DevPlace whenever you want me to work on your own account."
@@ -72,7 +98,9 @@ class DeviiSession:
settings.base_url, settings.timeout_seconds, settings.platform_api_key
)
self.avatar = AvatarController()
self.browser = ClientController(allow_eval=settings.allow_eval)
self.browser = ClientController(
allow_eval=settings.allow_eval, allow_control=settings.browser_control
)
self.store = task_store
self.task_controller = TaskController(self.store)
self.agentic = AgenticController(lessons, settings)
@@ -144,6 +172,7 @@ class DeviiSession:
self._turn_tool_calls = 0
self._pending_session: str | None = None
self._turns: set[asyncio.Task] = set()
self._turn_epoch = 0
def restore_history(self, messages: list[dict[str, Any]]) -> None:
if messages:
@@ -288,41 +317,79 @@ class DeviiSession:
await self._emit({"type": "clear"}, buffer=False)
def spawn_turn(self, text: str) -> None:
task = asyncio.create_task(self._run_turn(text))
epoch = self._turn_epoch
task = asyncio.create_task(self._run_turn(text, epoch))
self._turns.add(task)
task.add_done_callback(self._turns.discard)
async def cancel_turns(self) -> None:
self._turn_epoch += 1
turns = [task for task in self._turns if not task.done()]
if not turns:
return
for task in turns:
task.cancel()
await asyncio.gather(*turns, return_exceptions=True)
try:
await asyncio.wait_for(
asyncio.gather(*turns, return_exceptions=True), timeout=10
)
except asyncio.TimeoutError:
logger.warning(
"cancel_turns: a turn did not unwind within 10s for %s/%s (epoch-guarded)",
self.owner_kind,
self.owner_id,
)
async def reset(self) -> None:
await self.cancel_turns()
await self.reset_conversation()
await self._emit(
{"type": "status", "text": "Reset. Conversation cleared."}, buffer=False
)
async def _run_turn(self, text: str) -> None:
async def stop(self) -> None:
await self.cancel_turns()
async with self._lock:
_repair_history(self.agent._messages)
if self.persist_conversation:
try:
self._conv.save(
self.owner_kind, self.owner_id, self.agent._messages
)
except Exception: # noqa: BLE001 - persistence must not break the socket
logger.exception(
"Failed to persist history after stop for %s/%s",
self.owner_kind,
self.owner_id,
)
await self._emit({"type": "status", "text": "Stopped."}, buffer=False)
async def _run_turn(self, text: str, epoch: int) -> None:
turn_id = uuid_utils.uuid7().hex
started_at = _now_iso()
before = self._cost_snapshot()
self._turn_tool_calls = 0
reply = ""
error = ""
cancelled = False
try:
async with self._lock:
self._refresh_tools()
self._refresh_system_prompt()
reply = await self.agent.respond(text)
await self._emit({"type": "reply", "text": reply}, buffer=True)
if epoch == self._turn_epoch:
await self._emit({"type": "reply", "text": reply}, buffer=True)
except asyncio.CancelledError:
cancelled = True
raise
except Exception as exc: # noqa: BLE001 - reported to the browser, recorded for audit
error = str(exc)
logger.exception("Turn failed for %s/%s", self.owner_kind, self.owner_id)
await self._emit({"type": "error", "text": error}, buffer=True)
if epoch == self._turn_epoch:
await self._emit({"type": "error", "text": error}, buffer=True)
finally:
self._record_turn(turn_id, started_at, text, reply, error, before)
if not cancelled and epoch == self._turn_epoch:
self._record_turn(turn_id, started_at, text, reply, error, before)
def _refresh_tools(self) -> None:
builtin = CATALOG.tool_schemas_for(self.client.authenticated, self.is_admin)