From 72995550ba8cf15d5965f0165aeef7996a55dabf Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 08:22:46 +0000 Subject: [PATCH 1/2] feat(mcp): edit, merge and undo entities and topics from agents MCP gains edit_entity, edit_topic, merge_topics, delete_topic, undo_topic_change and undo_graph_change, calling the same routes (and checks) as the web app with a write-scope token. The assistant proposes topic merges, renames, definitions and deletes for approval (propose_topic_change), approvable in a chat room like entity changes. Approving clears the graph cache so the change shows at once. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01EzVhJCpwskyo5NhHEtS822 --- CHANGELOG.md | 4 + docs/assistant.md | 5 +- docs/chat-rooms.md | 2 +- docs/mcp.md | 12 +- docs/topics.md | 5 + fastapi_backend/app/api/mcp_tools.py | 155 ++++++++++++++++++- fastapi_backend/app/api/v1/routes/chats.py | 1 + fastapi_backend/app/domain/ai_tools.py | 78 ++++++++++ fastapi_backend/app/domain/bridge.py | 7 +- fastapi_backend/tests/api/test_mcp.py | 45 ++++++ fastapi_backend/tests/api/test_topics.py | 34 +++- nextjs-frontend/components/chat/steps.tsx | 1 + nextjs-frontend/components/settings/model.ts | 5 + threat-model.md | 1 + 14 files changed, 345 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cf9fe676b..681e608f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version - **Edit entities from a recording.** In a recording's **Entities** tab, the pencil next to an entity opens its side panel, so editors rename, retype, hide or merge it without leaving the recording ([Entities](docs/processing.md#entities-and-the-graph-explorer)). +- **Agents edit and merge entities and topics.** The MCP server has `edit_entity`, `edit_topic`, `merge_topics`, + `delete_topic`, `undo_topic_change` and `undo_graph_change` (with a write-scope token and editor access), and the + assistant proposes topic merges, renames, definitions and deletes for the person to approve + (`propose_topic_change`) ([MCP](docs/mcp.md), [Topics](docs/topics.md)). ## 0.9.0 October 15, 2026 {id="0.9.0"} diff --git a/docs/assistant.md b/docs/assistant.md index 2d3930927..9aa9ae291 100644 --- a/docs/assistant.md +++ b/docs/assistant.md @@ -98,8 +98,9 @@ When the configured model supports function calling, chat becomes an agent. `ai.max_steps` and `ai.max_transcript_reads`. - **Citations:** every moment a tool returns is numbered, so answers cite [n] across everything the assistant read. - **Visible steps:** each tool call streams as a step, for example 'Searched for "refund": 42 matches'. -- **Approvals:** running a template on recordings and changing entities (merging, renaming, retyping, describing one - and the other ways it's said, hiding one, or adding one to a namespace's fixed list) don't happen directly. +- **Approvals:** running a template on recordings, changing entities (merging, renaming, retyping, describing one + and the other ways it's said, hiding one, or adding one to a namespace's fixed list) and changing topics (merging, + renaming, describing or deleting one; [Topics](topics.md)) don't happen directly. They become approval cards (with the batch estimate) that the person approves, approves on a sample, or declines (`POST /api/v1/approvals/`). Viewers only get the read tools. - **Check sources** (`POST /api/v1/chats//messages//check`) re-checks every cited claim against the lines it diff --git a/docs/chat-rooms.md b/docs/chat-rooms.md index 5947a6cce..34bff45e1 100644 --- a/docs/chat-rooms.md +++ b/docs/chat-rooms.md @@ -114,7 +114,7 @@ That's all. Without an account given, it answers as the admin who turned it on. proposes (running work, changing settings) wait for approval in the web app, as in Chat; its answer says so and links to the conversation, through the Cloudflare tunnel while one is up (Settings › Remote access), so the link opens away from home too. -- **Approving in the room.** Reversible changes (merging, renaming or retyping entities, new namespaces) can be +- **Approving in the room.** Reversible changes (merging, renaming or retyping entities, changing topics, new namespaces) can be approved right there: the answer says "Reply “yes” to do it", and "yes" (or "no") does it (or declines it). With several waiting, "yes all" or "yes 12". Only the chat usernames listed may talk to Lens and approve, so it needs that list; **Approving in the room: only in the web app** turns it off. Settings, imports, batch runs, extensions diff --git a/docs/mcp.md b/docs/mcp.md index 8cf0b644f..9b8e56ab7 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -78,6 +78,12 @@ front of the web app also needs `TRUST_PROXY_HEADERS=true` ([Authentication](aut | `install_settings` | whether other devices on the network reach Lens and its edition (full or lean), whether the machine's upgrade agent can change them, and the install line to run when it can't. Admins only | | `set_install_settings` | open Lens to the network or keep it to this machine, or change the edition: the machine sets itself up again and Lens restarts ([Updates](updates.md#setting-the-machine-up-again)). Admins only, with a write-scope token | | `propose_graph_change` | ask for two entities to be merged or linked; it waits in Proposed changes unless `apply` makes it at once (it can be undone). Needs a write-scope token and editor access | +| `undo_graph_change` | take back a merge or link `propose_graph_change` made. Needs a write-scope token and editor access | +| `edit_entity` | rename an entity, change its type, describe it, set the other ways it's said, or hide or show it. Needs a write-scope token and editor access | +| `edit_topic` | rename a topic, set its other labels, definition, broader and related topics. Needs a write-scope token and editor access | +| `merge_topics` | fold topics into one; its `undo_id` takes it back. Needs a write-scope token and editor access | +| `delete_topic` | delete a topic; its `undo_id` takes it back. Needs a write-scope token and editor access | +| `undo_topic_change` | take back `merge_topics` or `delete_topic` by its `undo_id` ([Topics](topics.md#a-topic)). Needs a write-scope token and editor access | Results are JSON (as `structuredContent`, and the same as text). Links open the recording's page in the web app at that moment (`/resources/?t=`), on the address the client used. Mistakes the agent can fix (a wrong @@ -86,11 +92,13 @@ person's to read answers "not found", as the API does. `search` and `fetch` foll expect (`results` with `id`, `title`, `url`; `fetch` by that `id`). Every tool reads, except `suggest_topic`, which adds suggestions people accept or dismiss, `propose_graph_change`, -which records an undoable change (proposed by default), `write_note`, which adds a note, `create_podcast`, which +which records an undoable change (proposed by default), `undo_graph_change`, `edit_entity`, `edit_topic`, +`merge_topics`, `delete_topic` and `undo_topic_change`, which curate entities and topics as an editor does in the web +app (merges and deletes can be undone), `write_note`, which adds a note, `create_podcast`, which queues an episode, `set_nsfw` and `mark_nsfw`, which change [NSFW classification](nsfw.md) (owners or admins, and editors), `set_file_storage`, which changes where new files are kept (admins), and `set_monitoring` and `set_install_settings`, which have the machine change how Lens runs (admins). -Importing, editing and curating stay in the web app and the API. +Importing stays in the web app and the API. ### What the archive says is data diff --git a/docs/topics.md b/docs/topics.md index 3723f4aee..73ab6c736 100644 --- a/docs/topics.md +++ b/docs/topics.md @@ -131,3 +131,8 @@ The assistant in Chat finds topics (`find_topics`), reads one with its recording editors, suggests a topic for recordings (`suggest_topic`). The MCP server has the same as `list_topics`, `get_topic` and `suggest_topic` (with a write-scope token). Suggestions from either wait for someone to accept them, with `assistant` as their source; what people accepted or dismissed stays as it is. + +Asked to tidy the vocabulary, the assistant proposes merging, renaming, describing or deleting a topic +(`propose_topic_change`), which happens only when the person approves it, in Chat or with a yes in a chat room. With +a write-scope token, agents edit, merge and delete topics over MCP (`edit_topic`, `merge_topics`, `delete_topic`) and +take a merge or delete back with `undo_topic_change`. diff --git a/fastapi_backend/app/api/mcp_tools.py b/fastapi_backend/app/api/mcp_tools.py index 45101d7f3..3b1386cf1 100644 --- a/fastapi_backend/app/api/mcp_tools.py +++ b/fastapi_backend/app/api/mcp_tools.py @@ -30,6 +30,7 @@ from app.api.v1.routes import namespaces as namespace_routes from app.api.v1.routes import notebook as note_routes from app.api.v1.routes import recordings as recording_routes +from app.api.v1.routes import routines as routine_routes from app.api.v1.routes import search as search_routes from app.api.v1.routes import topics as topic_routes from app.domain import ( @@ -55,9 +56,10 @@ from app.domain import speakers as spk from app.domain import topics as topicmod from app.domain.store import DB -from app.schemas.entities import EntityList +from app.schemas.entities import EntityHide, EntityList, EntityRename, EntityRetype, EntityUpdate from app.schemas.notebook import NotePage from app.schemas.search import SearchResults +from app.schemas.topics import TopicMerge, TopicUpdate R = store.R FETCH_CHARS = 100_000 # the most of a transcript fetch returns; get_transcript pages through the rest @@ -1289,6 +1291,157 @@ def propose_graph_change(ctx: Context, kind: str, a: str, b: str, reason: str | return graph_routes.propose_graph_change(ctx.request, body, ctx.user, ctx.acl, ctx.db) +@tool( + "undo_graph_change", + "Undo a graph change", + "Take back a merge or link made by propose_graph_change (with apply, or once accepted): its id is the change's. " + "Needs a token with the write scope and editor access.", + Arg("change_id", "integer", "the change (propose_graph_change's id)", required=True), + writes=True, +) +def undo_graph_change(ctx: Context, change_id: int) -> dict[str, Any]: + _writer(ctx, "undo changes") + routine_routes.undo_graph_change(change_id, ctx.user, ctx.acl, ctx.db) + ctx.request.app.state.graph_cache.clear() + return {"undone": change_id} + + +# ---------- editing entities and topics (docs/graph.md, docs/topics.md) ---------- +def _writer(ctx: Context, what: str) -> None: + if not ctx.user.can_write: + raise ToolError(f"this token is read-only: ask for a token with the write scope to {what}") + + +@tool( + "edit_entity", + "Edit an entity", + "Rename an entity (the old name stays one of the ways it's said), change its type, describe it, set the other ways " + "it's said, or hide it (hidden false shows it again). Give only what changes. Renaming to another entity's name is " + "refused: merge them with propose_graph_change instead. Needs a token with the write scope and editor access.", + Arg("entity_id", "integer", "the entity (from list_entities or the graph's e)", required=True), + Arg("new_name", "string", "its new name", max_length=200), + Arg("new_type", "string", "its new type: PERSON, ORG, PRODUCT, PLACE, EVENT, WORK, TERM or one of the namespace's own", max_length=40), + Arg("description", "string", "what it is, in a sentence or two", max_length=2000), + Arg("aliases", "string[]", "the other ways it's said (these replace the ones it has)"), + Arg("hidden", "boolean", "hide it from lists and the graph, or show it again"), + writes=True, +) +def edit_entity( + ctx: Context, + entity_id: int, + new_name: str | None, + new_type: str | None, + description: str | None, + aliases: list[str] | None, + hidden: bool | None, +) -> dict[str, Any]: + _writer(ctx, "edit entities") + if new_name is None and new_type is None and description is None and aliases is None and hidden is None: + raise ToolError("say what changes: new_name, new_type, description, aliases or hidden") + args = (ctx.request, ctx.user, ctx.acl, ctx.db) + if new_name is not None: + entity_routes.rename_entity(entity_id, EntityRename(name=new_name), *args) + if new_type is not None: + entity_routes.retype_entities(EntityRetype(ids=[entity_id], type=new_type), *args) + if description is not None or aliases is not None: + body = EntityUpdate(**{k: v for k, v in (("description", description), ("aliases", aliases)) if v is not None}) + entity_routes.update_entity(entity_id, body, *args) + if hidden is not None: + entity_routes.hide_entity(entity_id, *args, body=EntityHide(hidden=hidden)) + d = entity_routes.get_entity(entity_id, ctx.user, ctx.acl, ctx.db) + return store.clean( + {"entity_id": d.id, "name": d.name, "type": d.type, "description": d.description, "aliases": d.aliases or None, "hidden": d.hidden} + ) + + +def _topic_out(d: Any) -> dict[str, Any]: + return store.clean( + { + "topic_id": d.id, + "label": d.label, + "also": d.alt or None, + "definition": d.definition, + "broader": [{"topic_id": x.id, "label": x.label} for x in d.broader] or None, + "related": [{"topic_id": x.id, "label": x.label} for x in d.related] or None, + } + ) + + +@tool( + "edit_topic", + "Edit a topic", + "Rename a topic, set its other labels or its definition, or what it is narrower than (broader_ids) or related to. " + "Give only what changes; lists replace the ones it has. Needs a token with the write scope and editor access.", + Arg("topic_id", "integer", "the topic (from list_topics or the graph's t)", required=True), + Arg("label", "string", "its new label", max_length=200), + Arg("also", "string[]", "its other labels: synonyms, abbreviations, spellings"), + Arg("definition", "string", "what it covers", max_length=2000), + Arg("broader_ids", "integer[]", "the topics it is narrower than", maximum=50), + Arg("related_ids", "integer[]", "the topics it is related to", maximum=50), + writes=True, +) +def edit_topic( + ctx: Context, + topic_id: int, + label: str | None, + also: list[str] | None, + definition: str | None, + broader_ids: list[int] | None, + related_ids: list[int] | None, +) -> dict[str, Any]: + _writer(ctx, "edit topics") + given = {"label": label, "alt": also, "definition": definition, "broader": broader_ids, "related": related_ids} + body = TopicUpdate(**{k: v for k, v in given.items() if v is not None}) + if not body.model_fields_set: + raise ToolError("say what changes: label, also, definition, broader_ids or related_ids") + return _topic_out(topic_routes.update_topic(topic_id, body, ctx.request, ctx.user, ctx.acl, ctx.db)) + + +@tool( + "merge_topics", + "Merge topics", + "Fold other topics of the same namespace into one: their labels become its other labels and the recordings about " + "them are about it. undo_id takes it back with undo_topic_change. Needs a token with the write scope and editor " + "access.", + Arg("keep_id", "integer", "the topic that stays", required=True), + Arg("other_ids", "integer[]", "the topics merged into it", required=True, maximum=50), + writes=True, +) +def merge_topics(ctx: Context, keep_id: int, other_ids: list[int]) -> dict[str, Any]: + _writer(ctx, "merge topics") + d = topic_routes.merge_topics(TopicMerge(keep=keep_id, others=other_ids), ctx.request, ctx.user, ctx.acl, ctx.db) + return {**_topic_out(d), "recordings": d.recordings, "undo_id": d.undo} + + +@tool( + "delete_topic", + "Delete a topic", + "Delete a topic: its narrower topics move up to its broader ones and recordings stop being about it. undo_id takes " + "it back with undo_topic_change. Needs a token with the write scope and editor access.", + Arg("topic_id", "integer", "the topic", required=True), + writes=True, +) +def delete_topic(ctx: Context, topic_id: int) -> dict[str, Any]: + _writer(ctx, "delete topics") + out = topic_routes.delete_topic(topic_id, ctx.request, ctx.user, ctx.acl, ctx.db) + return {"deleted": topic_id, "undo_id": out.undo} + + +@tool( + "undo_topic_change", + "Undo a topic merge or delete", + "Take back a merge_topics or delete_topic (by its undo_id): the topics come back with their labels, recordings and " + "pages. Refused when another topic has taken one of their labels since. Needs a token with the write scope and " + "editor access.", + Arg("undo_id", "integer", "what merge_topics or delete_topic gave back", required=True), + writes=True, +) +def undo_topic_change(ctx: Context, undo_id: int) -> dict[str, Any]: + _writer(ctx, "undo changes") + topic_routes.undo_topic_change(undo_id, ctx.request, ctx.user, ctx.acl, ctx.db) + return {"undone": undo_id} + + # ---------- notes (docs/notes.md) ---------- def _note_url(ctx: Context, pid: int) -> str: return f"{ctx.web}/notes/{pid}" diff --git a/fastapi_backend/app/api/v1/routes/chats.py b/fastapi_backend/app/api/v1/routes/chats.py index 8c2262998..9207483cf 100644 --- a/fastapi_backend/app/api/v1/routes/chats.py +++ b/fastapi_backend/app/api/v1/routes/chats.py @@ -422,4 +422,5 @@ def decide_approval(aid: int, body: ApprovalDecision, user: Writer, acl: Acl, db except (ValueError, PermissionError, KeyError) as e: raise HTTPException(400, str(e)) from None auth.audit(db, user.as_audit(), "assistant.approval", f"approval:{aid}", {"decision": body.decision, **out}) + request.app.state.graph_cache.clear() # an approved entity or topic change shows in the graph at once return out diff --git a/fastapi_backend/app/domain/ai_tools.py b/fastapi_backend/app/domain/ai_tools.py index f457b8d7e..041c1dff8 100644 --- a/fastapi_backend/app/domain/ai_tools.py +++ b/fastapi_backend/app/domain/ai_tools.py @@ -246,6 +246,22 @@ ["action"], True, ), + ( + "propose_topic_change", + "Propose a change to the topics, which needs the person's approval: merge other topics into a topic (their " + "labels become its other labels, their recordings are about it), rename it, describe it (a definition and its " + "other labels), or delete it. Merges and deletes can be undone afterwards.", + { + "action": {"type": "string", "enum": ["merge", "rename", "describe", "delete"]}, + "topic_id": _I, + "merge_ids": {"type": "array", "items": _I}, + "new_label": _S, + "definition": _S, + "other_labels": {"type": "array", "items": _S}, + }, + ["action", "topic_id"], + True, + ), ] @@ -1268,6 +1284,47 @@ def t_propose_entity_change( }[action] return self._approval("propose_entity_change", {**args, "entity_id": e["id"]}, what) + def t_propose_topic_change(self, action, topic_id, merge_ids=None, new_label=None, definition=None, other_labels=None): + needs = { + "merge": ("merge_ids", merge_ids), + "rename": ("new_label", new_label), + "describe": ("definition or other_labels", definition is not None or other_labels is not None), + "delete": ("topic_id", True), + } + if action not in needs: + raise ValueError("action is one of " + ", ".join(needs)) + if not needs[action][1]: + raise ValueError(f"{action} needs {needs[action][0]}") + t = self.db.one("SELECT record::id(id) AS id, space, label FROM $r", r=R("topic", int(topic_id))) + if not t or t["space"] not in self.readable: + raise ValueError(f"no topic {topic_id} in scope") + if t["space"] not in self.editable: + raise ValueError("changing topics needs editor access to the namespace") + others = [] + if action == "merge": + ids = [int(i) for i in dict.fromkeys(merge_ids) if int(i) != t["id"]] + rows = self.db.rows("SELECT record::id(id) AS id, space, label FROM topic WHERE id IN $ids", ids=[R("topic", i) for i in ids]) + if not ids or len(rows) != len(ids) or any(o["space"] != t["space"] for o in rows): + raise ValueError("merge_ids are other topics of the same namespace") + others = [o["label"] for o in rows] + args = { + "action": action, + "topic_id": t["id"], + "merge_ids": merge_ids, + "new_label": new_label, + "definition": definition, + "other_labels": other_labels, + } + what = { + "merge": f"Merge {', '.join(others)} into the topic {t['label']}", + "rename": f"Rename the topic {t['label']} to {new_label}", + "describe": f"Describe the topic {t['label']}" + + (f" as “{definition}”" if definition else "") + + (f" (also {', '.join(other_labels)})" if other_labels else ""), + "delete": f"Delete the topic {t['label']}", + }[action] + return self._approval("propose_topic_change", store.clean(args), what) + def cited(self, text): import re @@ -1328,6 +1385,8 @@ def _carry_out(db, cfg, a, user, editable, decision, base, admin, readable): confirm=f"RUN {len(ids)}", ) result = {"batch": bid} + elif a["tool"] == "propose_topic_change": + result = _topic_change(db, args, user, editable) elif args["action"] == "define": sid = {v: k for k, v in store.space_names(db).items()}.get(args["namespace"]) if sid not in editable: @@ -1359,6 +1418,25 @@ def _carry_out(db, cfg, a, user, editable, decision, base, admin, readable): return result +def _topic_change(db, args, user, editable): + """An approved change to the topics; a merge or delete says how to undo it.""" + tid = int(args["topic_id"]) + if (db.one("SELECT space FROM $r", r=R("topic", tid)) or {}).get("space") not in editable: + raise PermissionError("you can't change topics in that namespace") + act, by = args["action"], user["email"] + if act == "merge": + cid = topics.merge(db, tid, args.get("merge_ids") or [], user=by) + return {"topic": tid, "undo": cid} + if act == "delete": + _, cid = topics.delete(db, tid, user=by) + return {"deleted": tid, "undo": cid} + if act == "rename": + topics.update(db, tid, label=args["new_label"], user=by) + else: + topics.update(db, tid, alt=args.get("other_labels"), definition=args.get("definition"), user=by) + return {"topic": tid} + + def run_extension(db, cfg, args, user, admin, readable, toolbox=None): """An approved extension tool: the version that was proposed, if it's still on and still the person's to use.""" g = extensions.get(db, int(args["extension"]), args.get("version")) diff --git a/fastapi_backend/app/domain/bridge.py b/fastapi_backend/app/domain/bridge.py index abc4b5be9..aeddcfa93 100644 --- a/fastapi_backend/app/domain/bridge.py +++ b/fastapi_backend/app/domain/bridge.py @@ -363,9 +363,10 @@ def _answer(db, cfg, base, account, cid, q, files, act_on, outside): # ---------- approving in the room ---------- -# what can be approved by a reply in the room: changes to the graph (history keeps them, and they can be undone) and -# new namespaces; settings, imports, batch runs, extensions and forgetting are approved in the web app -ROOM_SAFE = {"propose_entity_change", "create_namespace"} +# what can be approved by a reply in the room: changes to the entities and topics (history keeps them, and merges and +# deletes can be undone) and new namespaces; settings, imports, batch runs, extensions and forgetting are approved in +# the web app +ROOM_SAFE = {"propose_entity_change", "propose_topic_change", "create_namespace"} YES_RX = re.compile(r"^(?:yes|y|yep|approve|approved|ok|okay|do it|go ahead)(?:\s+#?(\d+|all))?\s*[.!]*$", re.I) NO_RX = re.compile(r"^(?:no|n|nope|decline|cancel|don't)(?:\s+#?(\d+|all))?\s*[.!]*$", re.I) diff --git a/fastapi_backend/tests/api/test_mcp.py b/fastapi_backend/tests/api/test_mcp.py index 0e34bac9e..206c1d60e 100644 --- a/fastapi_backend/tests/api/test_mcp.py +++ b/fastapi_backend/tests/api/test_mcp.py @@ -75,6 +75,12 @@ def test_clients_are_sent_to_sign_in(client, app, env): assert [t["name"] for t in tools if not t["annotations"]["readOnlyHint"]] == [ "suggest_topic", "propose_graph_change", + "undo_graph_change", + "edit_entity", + "edit_topic", + "merge_topics", + "delete_topic", + "undo_topic_change", "write_note", "create_podcast", "set_nsfw", @@ -413,6 +419,45 @@ def test_topic_tools(client, db, env): assert tool_error(client, he, "suggest_topic", topic_id=gene, recording_ids=[env["ids"][2]]) # calls isn't theirs +def test_editing_topics_and_entities(client, db, env): + h = env["h"] # a read-only app token for a pods viewer + pods = store.ns_id(db, "pods") + bio = topics.create(db, pods, "Biology") + life = topics.create(db, pods, "Life sciences", alt=["bioscience"]) + dyno = tool(client, h, "list_entities", query="Dyno Therapeutics")["entities"][0]["entity_id"] + assert "read-only" in tool_error(client, h, "edit_topic", topic_id=bio, label="Biol") + assert "read-only" in tool_error(client, h, "merge_topics", keep_id=bio, other_ids=[life]) + assert "read-only" in tool_error(client, h, "edit_entity", entity_id=dyno, description="A gene therapy company.") + make_user(db, "ed@x.io", "editor password 1", roles={"pods": "editor"}) + he = login(client, "ed@x.io", "editor password 1") + # topics: edit, merge and undo, delete and undo + assert "say what changes" in tool_error(client, he, "edit_topic", topic_id=bio) + t = tool(client, he, "edit_topic", topic_id=bio, definition="Living things.", also=["bio"]) + assert (t["label"], t["also"], t["definition"]) == ("Biology", ["bio"], "Living things.") + m = tool(client, he, "merge_topics", keep_id=bio, other_ids=[life]) + assert m["also"] == ["bio", "Life sciences", "bioscience"] and m["undo_id"] + assert tool(client, he, "undo_topic_change", undo_id=m["undo_id"]) == {"undone": m["undo_id"]} + assert tool(client, h, "get_topic", topic_id=life)["label"] == "Life sciences" + assert "Nothing to undo" in tool_error(client, he, "undo_topic_change", undo_id=m["undo_id"]) + d = tool(client, he, "delete_topic", topic_id=life) + assert tool_error(client, h, "get_topic", topic_id=life) + tool(client, he, "undo_topic_change", undo_id=d["undo_id"]) + assert tool(client, h, "get_topic", topic_id=life)["also"] == ["bioscience"] + # entities: describe, say how else it's said, rename, hide and show + e = tool(client, he, "edit_entity", entity_id=dyno, description="A gene therapy company.", aliases=["Dyno"]) + assert (e["description"], e["aliases"]) == ("A gene therapy company.", ["dyno"]) # aliases are kept as keys + e = tool(client, he, "edit_entity", entity_id=dyno, new_name="Dyno Tx", hidden=True) + assert e["name"] == "Dyno Tx" and "dyno therapeutics" in e["aliases"] and e["hidden"] is True + assert tool(client, he, "edit_entity", entity_id=dyno, hidden=False)["hidden"] is False + assert "say what changes" in tool_error(client, he, "edit_entity", entity_id=dyno) + # merging entities goes through a graph change, which can be undone + other = client.post("/api/v1/namespaces/pods/entities", json={"name": "Dyno Inc", "type": "ORG"}, headers=he).json()["id"] + ch = tool(client, he, "propose_graph_change", kind="merge", a=f"e{dyno}", b=f"e{other}", apply=True) + assert ch["status"] == "applied" + assert tool(client, he, "undo_graph_change", change_id=ch["id"]) == {"undone": ch["id"]} + assert tool(client, h, "get_entity", entity_id=other)["entity_id"] == other + + def test_note_tools(client, db, env): h = env["h"] # a read-only app token for a pods viewer a, _, call = env["ids"] diff --git a/fastapi_backend/tests/api/test_topics.py b/fastapi_backend/tests/api/test_topics.py index 6d2e50eb3..ea407c19a 100644 --- a/fastapi_backend/tests/api/test_topics.py +++ b/fastapi_backend/tests/api/test_topics.py @@ -3,11 +3,13 @@ from __future__ import annotations +import json + import pytest from rdflib import Graph, URIRef from rdflib.namespace import SKOS -from app.domain import analyze, notebook, store, topics +from app.domain import ai_tools, analyze, notebook, store, topics from app.domain.store import R from tests.api.test_entities import Env @@ -165,6 +167,36 @@ def test_undo_deleting_a_topic_made_from_an_entity(env): assert (hist[0]["op"], hist[0]["why"]) == ("entity.hide", f"topic {t['id']} is back") +def test_the_assistant_proposes_topic_changes(env): + db, cfg = env.db, env.cfg + pods, calls = store.ns_id(db, "pods"), store.ns_id(db, "calls") + keep = topics.create(db, pods, "Funding") + grants = topics.create(db, pods, "Grants") + elsewhere = topics.create(db, calls, "Budgets") + me = {"id": 1, "email": "ed@x.io"} + box = ai_tools.Toolbox(db, cfg, me, {pods, calls}, {calls}, None, None) + assert box.call("propose_topic_change", {"action": "delete", "topic_id": grants})[1].endswith("needs editor access to the namespace") + box = ai_tools.Toolbox(db, cfg, me, {pods}, {pods}, None, None) + assert box.call("propose_topic_change", {"action": "rename", "topic_id": keep})[1] == "propose_topic_change: rename needs new_label" + assert box.call("propose_topic_change", {"action": "delete", "topic_id": elsewhere})[1].endswith(f"no topic {elsewhere} in scope") + merge = {"action": "merge", "topic_id": keep, "merge_ids": [elsewhere]} + assert box.call("propose_topic_change", merge)[1].endswith("other topics of the same namespace") + # nothing changes until the person says yes; a merge says how to undo it + out = json.loads(box.call("propose_topic_change", {**merge, "merge_ids": [grants]})[0]) + assert out["summary"] == "Merge Grants into the topic Funding" and db.one("SELECT id FROM $r", r=R("topic", grants)) + done = ai_tools.approve(db, cfg, out["approval"], me, {pods}) + assert done["status"] == "done" and not db.one("SELECT id FROM $r", r=R("topic", grants)) + topics.undo(db, done["undo"]) + assert topics.detail(db, grants, {pods})["label"] == "Grants" + out = json.loads(box.call("propose_topic_change", {"action": "describe", "topic_id": keep, "definition": "Money for work."})[0]) + ai_tools.approve(db, cfg, out["approval"], me, {pods}) + assert topics.detail(db, keep, {pods})["definition"] == "Money for work." + out = json.loads(box.call("propose_topic_change", {"action": "rename", "topic_id": keep, "new_label": "Funds"})[0]) + assert out["summary"] == "Rename the topic Funding to Funds" + assert ai_tools.approve(db, cfg, out["approval"], me, {calls}, decision="decline") == {"status": "declined"} + assert topics.detail(db, keep, {pods})["label"] == "Funding" + + def test_topics_in_the_graph_and_rdf(env): c, ed, vi = env.c, env.h["editor"], env.h["viewer"] bio = make(c, ed, "Biology") diff --git a/nextjs-frontend/components/chat/steps.tsx b/nextjs-frontend/components/chat/steps.tsx index 105fd8157..b14a02977 100644 --- a/nextjs-frontend/components/chat/steps.tsx +++ b/nextjs-frontend/components/chat/steps.tsx @@ -35,6 +35,7 @@ const ICON: Record = { speaker_stats: AudioLines, run_template: Play, propose_entity_change: PencilLine, + propose_topic_change: PencilLine, }; type Kind = "done" | "failed" | "waiting"; diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts index 2b31090c9..cdd04c5c8 100644 --- a/nextjs-frontend/components/settings/model.ts +++ b/nextjs-frontend/components/settings/model.ts @@ -488,6 +488,11 @@ export const AI_TOOLS: { name: string; label: string; acts: boolean }[] = [ label: "Propose entity merges, renames, type changes, descriptions and new entities", acts: true, }, + { + name: "propose_topic_change", + label: "Propose topic merges, renames, definitions and deletes", + acts: true, + }, { name: "import_files", label: "Import files sent in a conversation", acts: true }, { name: "import_urls", label: "Capture web pages from addresses or a list of links", acts: true }, { name: "server_status", label: "Check what the server has set up (admins)", acts: false }, diff --git a/threat-model.md b/threat-model.md index cd745e3c4..a5485eeeb 100644 --- a/threat-model.md +++ b/threat-model.md @@ -297,6 +297,7 @@ classified by gate only *(inferred, Q8)*; unread modules are listed in Q34. | workers and DB peers | DB credential, shared database rows | no (trusted peer) | x-peer | run peers on trusted hosts | *(inferred, Q9)* | | `.lens-control/inbox/upgrade` (host upgrade agent), `/metrics`, `.lens-control/prometheus-token` | `ref` (release tag or this install's branch; empty: the version running), with `https=`, `public=` (`0`/`1`) and `target=` (`full`/`lean`); `action=services` with `monitoring=on`/`off`; the scrape token | the inbox is writable by the containers (and local users); `/metrics` by anyone reaching the web app | x-env-config, credential | the agent installs only a release tag or the install's branch, changes only the HTTPS ports, the web app's network reach and the edition (any other value is dropped) and only toggles the `monitoring` profile, nothing else from the file, so a writer of the inbox can at most restart Lens with those choices or open it to the network; `/metrics` answers only the scrape token (constant-time compare); the token file is world-readable on the host and grants metrics only, which carry no personal content | *(documented, docs/updates.md, docs/prometheus.md "Privacy")* | | `PUT /api/v1/admin/install`, `POST /api/v1/settings/https/ports`, MCP `set_install_settings` | `public`, `target`, `open` | admin only (MCP: with the write scope) | x-env-config | admin is trusted; audited (`lens.install`, `https.ports`); the change reaches the machine only as an inbox request, which the agent checks again | *(documented, docs/updates.md "Setting the machine up again")* | +| MCP `edit_entity`, `edit_topic`, `merge_topics`, `delete_topic`, `undo_topic_change`, `undo_graph_change`; assistant `propose_topic_change` | entity and topic ids, names, labels, definitions | yes, an agent with an editor's write-scope token; indirectly through content the model reads | data, x-prompt-injection | the curate permission in each namespace touched and a write-capable principal (the same route functions as the web app); the assistant's changes wait for the person's approval; merges and deletes are kept to undo, and audited | *(documented, docs/mcp.md "curate entities and topics as an editor does")* | | `ask/NAME.want` in a microsandbox's `/data/.lens/programs` (LibreOffice and Chromium on first use) | a program's name | writable by the Lens user inside the sandbox | x-env-config | the start script, as root, installs only `libreoffice` or `chromium`, each a fixed list of signed Debian packages, and answers in `got/`, which only root writes; it reads nothing from the file but its name, and only deletes any other name or link | *(documented, docs/microsandbox.md "LibreOffice and Chromium")* | **Stateful postconditions.** A refused or failed one-time secret check consumes nothing; a used one is deleted before From 5d9bd4b609b35415a16342bcc3f4271c76484e5f Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 09:24:36 +0000 Subject: [PATCH 2/2] docs(threat-model): add the curation tools to the YAML and JSON companions The prose gained a row for the entity and topic curation tools; the companions now list the same entry point and carry the prose's hash. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01EzVhJCpwskyo5NhHEtS822 --- threat-model.json | 10 ++++++++++ threat-model.yaml | 11 ++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/threat-model.json b/threat-model.json index 735be68f9..fd496b8d8 100644 --- a/threat-model.json +++ b/threat-model.json @@ -52,6 +52,7 @@ "workers and DB peers", "host control inbox and the monitoring scrape token", "admin machine setup requests", + "entity and topic curation tools", "microsandbox program requests" ], "touches": [ @@ -519,6 +520,15 @@ "provenance": "documented", "source": "docs/updates.md \"Setting the machine up again\"" }, + { + "entry_point": "entity and topic curation tools", + "parameter": "MCP edit_entity, edit_topic, merge_topics, delete_topic, undo_topic_change, undo_graph_change; assistant propose_topic_change: entity and topic ids, names, labels, definitions", + "attacker_controllable": "yes", + "component": "authz", + "caller_must_enforce": "none — the curate permission in each namespace touched and a write-capable principal (the web app's own route functions); the assistant's changes wait for the person's approval; merges and deletes are kept to undo, and audited", + "provenance": "documented", + "source": "docs/mcp.md \"curate entities and topics as an editor does\"" + }, { "entry_point": "microsandbox program requests", "parameter": "ask/NAME.want in /data/.lens/programs: a program's name", diff --git a/threat-model.yaml b/threat-model.yaml index 17d6cc94c..d0c9a3ac8 100644 --- a/threat-model.yaml +++ b/threat-model.yaml @@ -2,7 +2,7 @@ # Authority order: prose > yaml > json. Regenerate whenever the prose changes. schema: threat-model-sidecar/v2 project: lens -prose_version: "threat-model.md@sha256:16e8f3084a18a5cc02c60dbf6ec3d75ea8ae614933ed4c72f0c2297eb26ff063" +prose_version: "threat-model.md@sha256:f430a4e9bedcf37ca6a5f5e2e782a3e72a9ac674b6dc78ebc91fc152af9e92a4" model_status: under-review triage_policy: strict confidence: {documented: 201, maintainer: 46, inferred: 91, assumption: 8} @@ -465,6 +465,15 @@ entry_points: obligation_id: admin-is-trusted caller_must_enforce: "admin is trusted; audited (lens.install, https.ports); reaches the machine only as an inbox request the agent checks again" provenance: {kind: documented, source: 'docs/updates.md "Setting the machine up again"'} + - id: "entity and topic curation tools" + component: authz + parameters: + - name: "MCP edit_entity, edit_topic, merge_topics, delete_topic, undo_topic_change, undo_graph_change; assistant propose_topic_change: entity and topic ids, names, labels, definitions" + attacker_controllable: true + x-condition: "an agent with an editor's write-scope token; indirectly through content the model reads" + control_kinds: [data, x-prompt-injection] + caller_must_enforce: "none — the curate permission in each namespace touched and a write-capable principal (the web app's own route functions); the assistant's changes wait for the person's approval; merges and deletes are kept to undo, and audited" + provenance: {kind: documented, source: 'docs/mcp.md "curate entities and topics as an editor does"'} - id: "microsandbox program requests" component: authz parameters: