Comments and Presence for Agents

Who Can Do What

What an agent may do follows its token, through the same gates as a share link:

• A full-access token on a document you can comment on adds, replies, resolves, reopens and shows presence. Commenting needs the access a Participant or Editor has; someone who can only view reads the threads.
• A read-only token lists threads but writes nothing: no comments and no presence.
• Presence is for API tokens only. A signed-in browser session already shows itself in the editor, so the presence endpoints answer it 403 presence_requires_token.

A comment an agent writes records the token's id for the audit trail, and the people reading it see only your name.

Reply, Resolve and Reopen

In the CLI, a thread is named by its element's ref, from any view:

livediagram comment add "Shop" n2 "Should this be idempotent?"   # starts a thread, or adds to one
livediagram comment reply "Shop" n2 "Yes, keyed by order id"
livediagram comment resolve "Shop" n2
livediagram comment reopen "Shop" n2

Add --tab Flow when the element is not on the first tab. reply, resolve and reopen on an element with no thread are refused, with the comment add command to start one.

Over the API, a thread is named by any comment in it, so take a comment id from the listing:

# Start a thread on an element (or add to its thread)
curl -X POST https://livediagram.app/api/documents/$DOC/tabs/$TAB/comments \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "elementId": "n2", "text": "Should this be idempotent?" }'

# Reply on the thread that holds comment c1f0…
curl -X POST https://livediagram.app/api/documents/$DOC/tabs/$TAB/comments/$COMMENT/reply \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "text": "Yes, keyed by order id" }'

# Resolve it, or reopen it
curl -X POST https://livediagram.app/api/documents/$DOC/tabs/$TAB/comments/$COMMENT/resolve \
  -H "Authorization: Bearer $TOKEN"
curl -X POST https://livediagram.app/api/documents/$DOC/tabs/$TAB/comments/$COMMENT/reopen \
  -H "Authorization: Bearer $TOKEN"

• Adding and replying answer 201 with the new comment. A comment is at most 2,000 characters, and a reply to a resolved thread reopens it, as it does in the editor.
• Resolving and reopening answer 204. Resolving a resolved thread, or reopening an open one, changes nothing.
• DELETE …/comments/$COMMENT deletes a comment you wrote. Removing someone else's is left to the editor.
• Arrows cannot carry a thread; every boxed element can.

Everyone with the document open sees each change arrive at once, exactly as if you had typed it. See Comments for how threads look in the editor.

Show What Your Agent Is Doing

An agent at work can appear on a tab with a short status line ("Adding the payment flow") and a focus: the elements it is looking at.

livediagram presence set "Shop" --status "Adding the payment flow" --focus api,db
livediagram presence set "Shop" --tab Flow --status "Reviewing" --ttl 120
livediagram presence clear "Shop"

curl -X PUT https://livediagram.app/api/documents/$DOC/tabs/$TAB/presence \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "status": "Adding the payment flow", "focus": ["api", "db"], "ttl": 60000 }'

{
  "presence": {
    "tabId": "tab-1",
    "status": "Adding the payment flow",
    "focus": ["api", "db"],
    "expiresAt": 1760180060000
  }
}

Setting presence again replaces both the status and the focus. DELETE on the same path takes it off at once and answers 204 whether or not it was there.

You rarely need to keep it alive yourself. Every changeset your token applies or reverts on a tab keeps its presence there for 30 seconds, so an agent that is busy editing stays visible and one that stops leaves on its own within two minutes at most. A dry run or a refused changeset refreshes nothing.

Refusals name what was wrong: 400 with status_too_long, invalid_status, too_many_focus, invalid_focus, ttl_out_of_range, focus_not_found (listing the refs) or focus_ambiguous (listing the candidates); 409 agent_presence_full when a document already shows 32 agents; and 503 room_unavailable when the live room could not be reached, which is worth one retry.

Waiting for People

To answer comments as they arrive, let the CLI wait for the next one rather than polling:

livediagram wait "Shop" --for comment --timeout 600

It prints the comment and exits, so an agent can read it, reply and wait again. Agents cannot be @mentioned; they read new comments as they arrive or on their next read.