Agents: open_branch and list_branches, docs and help (0.73.0)

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to DirXMLDevWeb are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.73.0] - 2026-10-22
+
+Needs DirXMLDev 0.50.0.
+
+### Added
+
+- **An agent moves between branches on its own:** MCP tools `open_branch` (work on another branch;
+  a new name branches from the base branch, nothing reaches the repository until a commit and push)
+  and `list_branches` (the projects, branches and base branch, and which you have open). Before,
+  an agent stayed on the branch its token's session first opened. The page and the agent each keep
+  their own branch.
+
+### Changed
+
+- **Docs and help for agents.** docs/agents.md now starts with a four-step quick start for Claude
+  Code, lists every MCP tool with its required and optional arguments and accepted values, the
+  resources and prompts, Cursor's and a script's connection, which branch an agent works on, and
+  what to do when it is refused. The agent tokens dialog says what the agent does next and links
+  there; `setup`'s summary names `/mcp__dirxmldev__setup`. The README, quickstart, tutorial,
+  features, upgrading, team-server install and security docs cover agents and their tokens.
+
 ## [0.72.0] - 2026-10-22
 
 Needs DirXMLDev 0.50.0.

README.md

@@ -86,7 +86,7 @@ pop-out window, and recording to a file.
 
 ## What it is, and is not
 
-It is a third client of the DirXMLDev core, next to the `idm` CLI and the MCP server. The page
+It is a third client of the DirXMLDev core, next to the `idm` CLI and DirXMLDev's MCP server. The page
 calls the same typed operations they call, so anything the core can do, it can do, with the
 same validation and the same refusals. It is not a port of Designer and contains no OpenText
 code. The tree on disk (in git) is the only state: edit here, with the CLI or with an agent, and
@@ -103,6 +103,12 @@ and pull requests, sign-in and audit. Every write goes through one review (a dry
 of the tree, file by file) and is applied as one transaction, or not at all. The whole list,
 view by view: [docs/features.md](docs/features.md).
 
+**Your agents too.** The server is an MCP server (`/mcp`). Make a token on the page, connect Claude
+Code, Cursor or a script, and run the `setup` prompt: the agent gets this version's rules, skills
+and docs from the server and acts as you, under your roles, with the same previews, plan and
+typed confirmation before a vault write as the page. The `idm`, `sim` and `apps` CLIs are in the
+image too. [docs/agents.md](docs/agents.md).
+
 ## Three ways to run it
 
 | | **Local** — one person, one container | **Server** — a team | **Workstation** — from a checkout |
@@ -129,6 +135,7 @@ for developing it or for a quick look at a tree. Upgrading an install is running
 | [docs/tutorial.md](docs/tutorial.md) | a new install to a first deploy: read a vault, change a policy, commit, deploy |
 | [docs/git-workflow.md](docs/git-workflow.md) | working with git: branches, dev/test/production of one driver set, promotion, merging into main, remotes |
 | [docs/features.md](docs/features.md) | every view, by area |
+| [docs/agents.md](docs/agents.md) | agents: tokens, connecting Claude Code or Cursor, the setup prompt, every MCP tool and its arguments, the CLIs, the agent kit |
 | [docs/data-model.md](docs/data-model.md) | projects, workspaces, trees, environments and vaults: the entity relationship diagram |
 | [docs/multi-user.md](docs/multi-user.md) | design note: per-user connections, data and traces on a hosted server |
 | [docs/architecture-view.md](docs/architecture-view.md) | design note: the Architecture (Designer Modeler) and Developer views |

bin/smoke-hosted.sh

@@ -287,6 +287,16 @@ check("MCP: another host is refused", s == 403)
 s, _, _ = anon.call("POST", "/mcp", {"jsonrpc": "2.0", "id": 7, "method": "tools/list"}, csrf=False)
 check("MCP: without a token it says to sign in", s == 401)
 check("MCP: GET has no stream (405)", ci.call("GET", "/mcp", headers=mine)[0] == 405)
+page_branch = alice.call("GET", "/api/session")[1]["branch"]
+s, ob, _ = mcp({"jsonrpc": "2.0", "id": 13, "method": "tools/call", "params": {"name": "open_branch", "arguments": {"branch": "feature/agent-moved"}}})
+s, r, _ = mcp({"jsonrpc": "2.0", "id": 14, "method": "tools/call", "params": {"name": "session", "arguments": {}}})
+check("MCP: open_branch moves the agent to another branch", not ob["result"]["isError"] and json.loads(r["result"]["content"][0]["text"])["branch"] == "feature/agent-moved")
+check("MCP: ... and the page stays on its own", alice.call("GET", "/api/session")[1]["branch"] == page_branch)
+s, lb, _ = mcp({"jsonrpc": "2.0", "id": 15, "method": "tools/call", "params": {"name": "list_branches", "arguments": {}}})
+check("MCP: list_branches names the branch the agent opened as one of yours", "feature/agent-moved" in lb["result"]["content"][0]["text"])
+s, bad, _ = mcp({"jsonrpc": "2.0", "id": 16, "method": "tools/call", "params": {"name": "open_branch", "arguments": {"branch": "../escape"}}})
+check("MCP: a bad branch name is refused", bad["result"]["isError"])
+mcp({"jsonrpc": "2.0", "id": 17, "method": "tools/call", "params": {"name": "open_branch", "arguments": {"branch": page_branch}}})
 s, rl, _ = mcp({"jsonrpc": "2.0", "id": 8, "method": "resources/list"})
 uris = [x["uri"] for x in rl["result"]["resources"]]
 check("MCP: the agent kit is listed as resources", s == 200 and "dirxmldev://kit/AGENTS.md" in uris)