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.

docs(society): record the agent's own hands - shell, browser, learned skills

rubenluetke10-beep2b5ae1b01eac
diff --git a/docs/agent-society/MASTERPLAN.md b/docs/agent-society/MASTERPLAN.md
index b828196221..05c4979031 100644
--- a/docs/agent-society/MASTERPLAN.md
+++ b/docs/agent-society/MASTERPLAN.md
@@ -13,8 +13,12 @@ model, tools and briefing apply in full; the turn's end is a RESULT on the board
stack stays available via `payload.runner = "mission"`), the starter team Scout + Archivist is
seeded once per install, seed proposals come from connected capabilities
(`GET /api/society/seeds`), and the voice front door exists: router tools `delegate-to-agent`
-and `society-status` (ADR-0011 amendment). **M3 world** is the maintainer's parallel track.
-Open in M4: rooms live under the scheduler, the curator.
+and `society-status` (ADR-0011 amendment). **Agent mechanics wave (2026-09-02):** every agent
+has its own contained shell and file hands, its own persistent browser through browser-use
+(out of process, login sessions for the user's accounts, attach mode), and learns
+automatically — finished tasks become skills in its own namespace (see
+`agent-definition.md` §3.1). **M3 world** is the maintainer's parallel track. Open in M4:
+rooms live under the scheduler, the curator.
The research behind every claim here lives in [`research/`](research/):
[Branch A — product & UI](research/branch-a-product-ui.md) (Hermes Agent, Grok Bot, 3D stack,
diff --git a/docs/agent-society/agent-definition.md b/docs/agent-society/agent-definition.md
index 29282fbedd..6874b37b0b 100644
--- a/docs/agent-society/agent-definition.md
+++ b/docs/agent-society/agent-definition.md
@@ -96,6 +96,22 @@ read-only view over them — `jarvis/society/capabilities.py` — that returns t
| `skill` | `skill:<slug>` | `jarvis/skills/registry.py`, `active` lifecycle only | always (skills are text) |
| `core` | `core:<tool>` (`core:search-web`, `core:wiki-recall`, `core:run-shell`, `core:computer-use`, `core:read/write/edit` folder tools) | the built-in tool set minus the router-only dispatch tools | always |
+**The agent's own hands (built 2026-09-02, all in `jarvis/society/`):**
+
+| tool | what | gate |
+|---|---|---|
+| `society_shell` | commands in the agent's OWN workspace folder (`data/society/<id>/workspace`), path containment, output cap, timeout — local by decision (Hermes' default backend is local, OpenClaw's sandbox is off by default); `ShellBackend` is the seam for a later Docker backend | destructive class → `ask`; `approvals.decide` on `core:shell` |
+| `Read/Write/Edit/Ls/Glob/Grep` | the chat's folder tools, wrapped so every path stays inside the workspace | folder tiers |
+| `society_browser` | one browser-use run in the agent's persistent Chromium profile (or its attached Chrome), out of process in a managed venv (`jarvis/society/browser/`), capped steps and time, results and cost on the board | send/buy/delete/publish wording → `ask`; `approvals.decide` on `core:browser`; `browser_allowed_domains` |
+| `society_run_skill` | loads one of the agent's learned skills as instructions | monitor |
+| `society_message_agent`, `society_wiki_note` | see §4 and §5 | monitor |
+
+**Learning (automatic, maintainer decision 2026-09-02):** after a finished chat-run task the
+turn is digested and, when a procedure emerged, authored into `data/society/<id>/skills/<slug>/`
+— active for that agent immediately, listed in its briefing, promotable to the global user
+skills as a draft (`POST /agents/{id}/skills/{slug}/promote`). Daily cap per agent; a memory
+line on the agent's wiki page; a notice in its chat.
+
Never in any society tool set, structurally (AP-5/AP-14): `spawn-worker`, `spawn-subagents`,
`multi-spawn`, `dispatch-*`, `create-artifact`, `navigate`, `switch-provider`,
`manage-mcp-server`, `app-command`. Dispatch is the scheduler's privilege; app control stays
diff --git a/docs/os-parity.md b/docs/os-parity.md
index b7137620f1..a1a208fb67 100644
--- a/docs/os-parity.md
+++ b/docs/os-parity.md
@@ -210,6 +210,7 @@ implementations, not stubs.
| Voice / audio (capture, playback, VAD, wake, STT, TTS, realtime) | Clean; headless disables voice honestly; WASAPI logic is inert-by-data off Windows |
| Core (launcher, config, keyring, restart, autostart, tray, elevation, paths) | Clean; per-OS autostart (Registry / LaunchAgent / XDG `.desktop`), keyring falls back to a 0600 file on headless hosts |
| Data / agents (wiki, contacts, telephony, sessions, missions, skills, self-mod, channels, MCP) | Clean; mission workers run on POSIX with a real process-group reaper |
+| Agent society hands (own shell, browser via browser-use, learned skills) | Shell: local subprocess in the agent's workspace on every OS (Git Bash/PowerShell/bash/sh pick as the chat's folder tools), no container by decision. Browser: browser-use lives in a managed venv under the data dir (its pins collide with the app's), installed on demand — `uv`/`venv`, a 3.11–3.13 interpreter preferred, Chromium downloaded once; headless runs need no display, so a headless Linux box runs agents' browsers; the headed login session needs a display (409 without one is the follow-up); attach mode needs a running Chrome with `--remote-debugging-port`. Learning is pure files + the brain, OS-neutral |
| Agent society substrate (roster, typed board, scheduler, rooms, mission bridge, `/api/society`) | Clean; pure asyncio + SQLite (`data/society.db`, WAL) and FastAPI, no OS API, no GPU, no audio. Full REST parity from a headless `python:3.11-slim` (`tests/contract/test_society_substrate.py` seeds two agents and exchanges typed messages with fakes only); the dynamic `jarvis api society …` CLI layer covers every route. FTS5 over knowledge summaries is optional — a SQLite without it degrades to plain reads (same class as P-05). Per-agent screens (`agent_screen`) are M6 and keep their own per-OS probes |
| Typed chat on the Jarvis surface (brain runner, folder tools, approval card, CLI seats as Jarvis) | Clean; pure asyncio + SQLite, no OS API. Every CLI spawn keeps `NO_WINDOW_CREATIONFLAGS` and UTF-8 stdio. The identity for a Claude Code seat travels as a FILE under the app data dir (`jarvis_harness.write_identity_file`, removed after the turn) because Windows caps a command line at 32 767 characters; Codex and agy take it on stdin (no limit), Grok Build a compact cut on argv (`COMPACT_MAX_CHARS`). The MCP session header and the approval bridge are transport-level and OS-neutral |
diff --git a/jarvis/society/README.md b/jarvis/society/README.md
index 49188f0541..80651213d0 100644
--- a/jarvis/society/README.md
+++ b/jarvis/society/README.md
@@ -20,7 +20,11 @@ live under the scheduler and the voice router tool (M4) are not.
| `approvals.py` | the unattended ask-queue: require > always-allow > tier vs ceiling; expiry parks, never drops |
| `routines.py` | per-agent routines as tagged Automations tasks |
| `surface.py` | the `society` chat surface: per-session hands (grant/focus/deny), the briefing, the ecosystem card |
-| `agent_tools.py` | `society_message_agent` (one typed envelope to ONE teammate) and `society_wiki_note` (writes only under `society/<agent>/`) |
+| `agent_tools.py` | `society_message_agent` (one typed envelope to ONE teammate), `society_wiki_note` (writes only under `society/<agent>/`), `society_shell` (the agent's own contained shell) |
+| `shell.py` | the shell backend seam: `LocalBackend` now (local by decision), path containment, caps |
+| `browser/` | the agent's browser: one-click venv install of browser-use, the in-venv runner, per-agent persistent profiles + login sessions, `society_browser` |
+| `learning.py` | automatic learning: turn digest → skill in the agent's own namespace, `society_run_skill`, promotion to the global registry as a draft |
+| `seeds.py` | the starter team (Scout + Archivist) and proposals from connected capabilities |
| `chat_binding.py` | roster row → canonical `agent_chat` session; delivers board envelopes as framed turns |
| `runtime.py` | the lazily built singleton wiring all of it; `current_runtime()` for the surface |