Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Prototype shared swarm collaboration and inline comments

deeeb13603bed8d
diff --git a/docs/prototypes/collaboration/README.md b/docs/prototypes/collaboration/README.md
new file mode 100644
index 000000000..7f61ee334
--- /dev/null
+++ b/docs/prototypes/collaboration/README.md
@@ -0,0 +1,48 @@
+# Shared swarm collaboration prototype
+
+Open `index.html` in a browser. No build, package installation, server, or account is required.
+
+For a local web preview, run this from the repository root and open <http://127.0.0.1:8766/>:
+
+```sh
+python3 -m http.server 8766 --bind 127.0.0.1 --directory docs/prototypes/collaboration
+```
+
+This is a disposable concept prototype. All changes stay in this directory; the Harness app is not connected or modified.
+
+## Try it
+
+1. **Agent A** starts with a sample comment from Alice on your prompt. Reply from your view and watch the reply appear in Alice’s view.
+2. Highlight any portion of a prompt or agent output, for example **“All 3 auth tests passed”** in Agent B. Click the floating **Comment** button, type feedback, and post it. The shortcut is **Ctrl+Alt+M** or **Cmd+Option+M** after selecting text.
+3. In the other view, click the new yellow highlight or the pane’s **Comments** button. Reply to the same thread. The author and reply appear in both views.
+4. Select another passage to start a separate thread. Selections can span multiple entries in the same pane. Each thread keeps its exact quoted text; adding output, moving a pane, or closing and restoring it preserves the discussion.
+5. Close a comment panel and click a yellow passage to reopen its thread. Reading a thread and writing a draft are local; posted comments and highlights are shared.
+6. Send prompts to **any agent from either view**, including while it is working. Prompts and scripted activity appear in both views. Comments never send a prompt or trigger a simulated run.
+7. Move, resize, maximize, rename, add, or close an agent pane. Both views receive the same change. **Undo removal** restores the same agent, output, and comments.
+8. Open **Share** in your view. Change Alice to **Can view**: she can read comments and output but cannot post, prompt, or change the swarm. Invite another person to try joining with either permission.
+9. Use **Reset demo** to start again.
+
+## Scope
+
+- One shared swarm with three agents and two visible participant views.
+- Shared pane membership, order, size, maximized state, names, prompts, and output.
+- Independent unsent drafts, text selection, keyboard focus, scrolling, and comment reading.
+- Anyone with work access can message any agent or stop it. There are no control handoffs.
+- Swarm-wide **Can work** and **Can view** permissions.
+- Comments anchored to exact text selections, shared yellow highlights, quoted passages, author attribution, and replies. No general pane chat, notifications, or resolve workflow in this iteration.
+- A pane close removes it for everyone and keeps its simulated runtime alive.
+
+Both views render one in-memory state. This is not a networked multiplayer implementation, a terminal emulator, or a connection to real agents. Output is scripted, identities and invitations are simulated, and refreshing the page resets everything. A permission switch demonstrates the interaction; it is not a security boundary.
+
+The fake agent processes sample responses in sequence solely to keep the demo interactive. A real integration would reuse the agent’s existing input behavior. Comments use stable transcript entry IDs and text offsets plus a saved quote. They demonstrate the interaction without attempting to map a real terminal’s cells, scrollback, or redraws.
+
+The **Share** dialog does not send email or create a real invitation link. Real authentication, persistence, encryption, machine grants, billing, file effects, and disconnection recovery are outside this prototype.
+
+## Files
+
+- `index.html`: the two client shells and small dialogs.
+- `styles.css`: basic layout and controls.
+- `app.js`: shared state, interactions, and scripted agent runs.
+- `comments.js`: text selection, passage highlights, and shared comment threads.
+
+Keep this implementation simple while changing the collaboration concepts. It is not intended to be moved directly into production.
diff --git a/docs/prototypes/collaboration/app.js b/docs/prototypes/collaboration/app.js
new file mode 100644
index 000000000..5fa4e5f42
--- /dev/null
+++ b/docs/prototypes/collaboration/app.js
@@ -0,0 +1,432 @@
+// A single in-memory swarm, rendered through two simulated clients.
+// Agent output is scripted. This file makes no network or runtime calls.
+(() => {
+ "use strict";
+ const $ = (selector, root = document) => root.querySelector(selector);
+ const $$ = (selector, root = document) => [...root.querySelectorAll(selector)];
+ const views = $$(".client").map(root => ({ root, body: $(".workspace", root), panes: new Map() }));
+ const drafts = new Map();
+ const timers = new Set();
+ let state;
+ let nextAgent;
+ let rightPerson;
+ let runSequence = 0;
+ const comments = createPaneComments({ views, viewPerson, canWork, personName, announce, render,
+ getAgent: id => state.agents[id] });
+
+ function element(tag, className, text) {
+ const node = document.createElement(tag);
+ if (className) node.className = className;
+ if (text !== undefined) node.textContent = text;
+ return node;
+ }
+ function button(label, action, title) {
+ const node = element("button", "", label);
+ node.type = "button";
+ node.dataset.action = action;
+ if (title) { node.title = title; node.setAttribute("aria-label", title); }
+ return node;
+ }
+ function member(id) { return state.members.find(person => person.id === id); }
+ function personName(id) { return id === "owner" ? "Owner" : member(id)?.name || "Someone"; }
+ function canWork(id) {
+ const person = member(id);
+ return person?.joined && person.role !== "viewer";
+ }
+ function viewPerson(view) { return view.root.dataset.client === "left" ? "owner" : rightPerson; }
+ function draftKey(personId, agentId) { return personId + ":" + agentId; }
+ function announce(message) { state.notice = message; $("#announcement").textContent = message; }
+ function append(agent, kind, text, sender) {
+ agent.log.push({ id: agent.id + "-line-" + agent.log.length, kind, text, sender });
+ }
+ function createAgent(id, name, engine, machine) {
+ const agent = { id, name, engine, machine, size: "small", status: "idle", run: 0,
+ log: [], threads: [], commentVersion: 0, demoInputs: [] };
+ append(agent, "system", "Session ready · sample-app");
+ return agent;
+ }
+ function schedule(fn, delay) {
+ const timer = setTimeout(() => { timers.delete(timer); fn(); }, delay);
+ timers.add(timer);
+ }
+
+ function reset() {
+ for (const timer of timers) clearTimeout(timer);
+ timers.clear();
+ drafts.clear();
+ nextAgent = 4;
+ rightPerson = "alice";
+ comments.reset();
+ $("#announcement").textContent = "";
+ state = {
+ name: "Release", maximized: null, notice: "", removed: [],
+ members: [
+ { id: "owner", name: "You", role: "owner", joined: true },
+ { id: "alice", name: "Alice", role: "editor", joined: true }
+ ],
+ order: ["a", "b", "c"],
+ agents: {
+ a: createAgent("a", "Agent A · implementation", "Codex", "Your Mac mini"),
+ b: createAgent("b", "Agent B · tests", "Claude", "Alice’s laptop"),
+ c: createAgent("c", "Agent C · review", "Codex", "Your build machine")
+ }
+ };
+ append(state.agents.a, "user", "Rewrite the authentication module.", "owner");
+ append(state.agents.a, "agent", "The expired-token check needs a regression test. Ready for the next instruction.");
+ append(state.agents.b, "user", "Run the auth tests.", "alice");
+ append(state.agents.b, "result", "All 3 auth tests passed. The login flow is ready for review.");
+ append(state.agents.c, "agent", "Ready to review the next change.");
+ comments.seed(state.agents.a, state.agents.a.log[1], "alice", "Could we narrow this to the token refresh bug?");
+ for (const dialog of $$("dialog")) if (dialog.open) dialog.close();
+ for (const view of views) { view.panes.clear(); view.body.replaceChildren(); buildWorkspace(view); }
+ render();
+ }
+
+ function buildWorkspace(view) {
+ const header = element("div", "swarm-header");
+ const title = element("input", "swarm-title");
+ title.setAttribute("aria-label", "Swarm name");
+ title.maxLength = 50;
+ title.addEventListener("blur", () => {
+ const value = title.value.trim();
+ if (canWork(viewPerson(view)) && value && value !== state.name) {
+ state.name = value;
+ announce(personName(viewPerson(view)) + " renamed the swarm.");
+ }
+ title.value = state.name;
+ render();
+ });
+ title.addEventListener("keydown", event => { if (event.key === "Enter") title.blur(); });
+ const tools = element("div", "swarm-tools");
+ tools.append(button("Show all agents", "restore"), button("+ Agent", "add"), button("Share", "share"));
+ header.append(title, tools);
+ const presence = element("div", "presence");
+ const notice = element("div", "notice");
+ notice.append(element("span", "notice-text"), button("Undo removal", "undo"));
+ const grid = element("div", "agent-grid");
+ const empty = element("div", "empty", "No agents in this swarm.");
+ const join = element("div", "join-screen");
+ join.append(element("h2", "", "You’re invited"), element("p", "invitation"), button("Join swarm", "join"));
+ view.body.append(header, presence, notice, grid, empty, join);
+ if (!view.actionsBound) {
+ view.actionsBound = true;
+ view.body.addEventListener("click", event => {
+ const control = event.target.closest("button[data-action]");
+ if (!control || control.disabled) return;
+ const agentId = control.closest("[data-agent]")?.dataset.agent;
+ act(control.dataset.action, viewPerson(view), agentId);
+ });
+ }
+ }
+
+ function buildPane(view, agent) {
+ const pane = element("section", "agent");
+ pane.dataset.agent = agent.id;
+ const header = element("div", "agent-header");
+ const heading = element("div", "agent-heading");
+ const name = element("input", "agent-name");
+ name.maxLength = 55;
+ name.addEventListener("blur", () => {
+ const value = name.value.trim();
+ if (canWork(viewPerson(view)) && state.order.includes(agent.id) && value && value !== agent.name) {
+ agent.name = value;
+ announce(personName(viewPerson(view)) + " renamed an agent.");
+ }
+ name.value = agent.name;
+ render();
+ });
+ name.addEventListener("keydown", event => { if (event.key === "Enter") name.blur(); });
+ heading.append(name, element("div", "agent-meta"));
+ const tools = element("div", "pane-tools");
+ tools.append(
+ button("↑", "up", "Move pane up for everyone"),
+ button("↓", "down", "Move pane down for everyone"),
+ button("↕", "size", "Expand or shrink pane for everyone"),
+ button("□", "maximize", "Maximize pane for everyone"),
+ button("×", "remove", "Remove pane for everyone; keep agent running")
+ );
+ header.append(heading, tools);
+ const control = element("div", "control-bar");
+ const actions = element("div", "control-actions");
+ actions.append(button("Stop", "interrupt"));
+ const commentToggle = button("Comments", "comments", "Open comments");
+ commentToggle.addEventListener("click", event => { event.stopPropagation(); comments.toggle(view, agent); });
+ actions.append(commentToggle);
+ control.append(element("span", "control-label"), actions);
+ const transcript = element("div", "transcript");
+ transcript.setAttribute("role", "log");
+ transcript.setAttribute("aria-live", "off");
+ const form = element("form", "prompt-form");
+ const input = element("textarea");
+ input.rows = 2;
+ const send = element("button", "send", "Send");
+ send.type = "submit";
+ form.append(input, send);
+ input.addEventListener("input", () => {
+ drafts.set(draftKey(viewPerson(view), agent.id), input.value);
+ updateSend();
+ });
+ function updateSend() {
+ send.disabled = !input.value.trim() || !canWork(viewPerson(view));
+ }
+ function submit(event) {
+ event.preventDefault();
+ if (sendPrompt(viewPerson(view), agent.id, input.value)) {
+ input.value = "";
+ drafts.delete(draftKey(viewPerson(view), agent.id));
+ updateSend();
+ }
+ }
+ form.addEventListener("submit", submit);
+ input.addEventListener("keydown", event => {
+ if (event.key === "Enter" && !event.shiftKey && !event.isComposing) submit(event);
+ });
+ const main = element("div", "agent-main");
+ main.append(transcript, form);
+ const conversation = element("div", "pane-conversation");
+ conversation.append(main, comments.buildPanel(view, agent));
+ pane.append(header, control, conversation);
+ pane.refreshSend = updateSend;
+ pane.renderedEntries = 0;
+ return pane;
+ }
+
+ function renderPane(view, pane, agent, index) {
+ const personId = viewPerson(view);
+ const writable = canWork(personId);
+ pane.classList.toggle("large", agent.size === "large");
+ pane.classList.toggle("maximized", state.maximized === agent.id);
+ pane.hidden = Boolean(state.maximized && state.maximized !== agent.id);
+ pane.setAttribute("aria-label", agent.name);
+ const name = $(".agent-name", pane);
+ if (document.activeElement !== name) name.value = agent.name;
+ name.disabled = !writable;
+ name.setAttribute("aria-label", "Name of " + agent.name);
+ $(".agent-meta", pane).textContent = agent.engine + " · " + agent.machine;
+ $(".pane-tools", pane).hidden = !writable;
+ $('[data-action="up"]', pane).disabled = index === 0;
+ $('[data-action="down"]', pane).disabled = index === state.order.length - 1;
+ $('[data-action="size"]', pane).title = agent.size === "large" ? "Shrink pane for everyone" : "Expand pane for everyone";
+ $('[data-action="maximize"]', pane).textContent = state.maximized === agent.id ? "▣" : "□";
+ $(".control-label", pane).textContent = agent.status === "working" ? "Working" : "Ready";
+ $('[data-action="interrupt"]', pane).hidden = !writable || agent.status !== "working";
+ const log = $(".transcript", pane);
+ log.setAttribute("aria-label", agent.name + " shared output");
+ const atBottom = log.scrollHeight - log.clientHeight - log.scrollTop < 28;
+ const selection = window.getSelection();
+ const selectingText = selection && !selection.isCollapsed && log.contains(selection.anchorNode);
+ for (let i = pane.renderedEntries; i < agent.log.length; i++) {
+ const entry = agent.log[i];
+ const line = element("div", "entry entry-" + entry.kind);
+ line.dataset.entry = entry.id;
+ if (entry.kind === "user") {
+ line.append(element("span", "sender", personName(entry.sender) + " › "));
+ }
+ line.append(element("span", "entry-text", entry.text));
+ log.append(line);
+ }
+ if (!selectingText && pane.renderedEntries !== agent.log.length && (atBottom || pane.renderedEntries === 0)) log.scrollTop = log.scrollHeight;
+ pane.renderedEntries = agent.log.length;
+ const input = $(".prompt-form textarea", pane);
+ if (input.dataset.person !== personId) {
+ input.value = drafts.get(draftKey(personId, agent.id)) || "";
+ input.dataset.person = personId;
+ }
+ input.disabled = !writable;
+ input.placeholder = writable ? "Message this agent…" : "View only";
+ input.setAttribute("aria-label", "Prompt " + agent.name);
+ $(".send", pane).title = "Send prompt · Shift+Enter for a new line";
+ pane.refreshSend();
+ comments.renderPane(view, pane, agent);
+ }
+
+ function render() {
+ const select = $("#teammate-select");
+ const people = state.members.filter(person => person.id !== "owner");
+ if (select.options.length !== people.length) {
+ select.replaceChildren(...people.map(person => {
+ const option = element("option", "", person.name);
+ option.value = person.id;
+ return option;
+ }));
+ }
+ select.value = rightPerson;
+ for (const view of views) {
+ const person = member(viewPerson(view));
+ const body = view.body;
+ const joined = person?.joined;
+ const writable = canWork(person.id);
+ const title = $(".swarm-title", body);
+ if (document.activeElement !== title) title.value = state.name;
+ title.disabled = !writable;
+ $('[data-action="share"]', body).hidden = person.role !== "owner";
+ $('[data-action="add"]', body).hidden = !writable;
+ $('[data-action="restore"]', body).hidden = !state.maximized || !writable;
+ $(".presence", body).textContent = state.members.filter(p => p.joined).map(p => personName(p.id)).join(" · ") + " / " + (person.role === "owner" ? "Owner" : person.role === "editor" ? "Can work" : "Can view");
+ const notice = $(".notice", body);
+ notice.hidden = !state.notice || !joined;
+ $(".notice-text", notice).textContent = state.notice;
+ $('[data-action="undo"]', notice).hidden = !state.removed.length || !writable;
+ const grid = $(".agent-grid", body);
+ grid.hidden = !joined;
+ $(".empty", body).hidden = !joined || state.order.length > 0;
+ $(".join-screen", body).hidden = Boolean(joined);
+ $(".invitation", body).textContent = "You were invited to " + state.name + " with " + (person.role === "viewer" ? "view" : "work") + " access.";
+ for (const [id, pane] of view.panes) {
+ if (!state.order.includes(id)) { pane.remove(); view.panes.delete(id); }
+ }
+ state.order.forEach((id, index) => {
+ let pane = view.panes.get(id);
+ if (!pane) { pane = buildPane(view, state.agents[id]); view.panes.set(id, pane); }
+ if (grid.children[index] !== pane) grid.insertBefore(pane, grid.children[index] || null);
+ renderPane(view, pane, state.agents[id], index);
+ });
+ }
+ }
+
+ function sendPrompt(personId, id, rawText) {
+ const agent = state.agents[id];
+ const text = rawText.trim();
+ if (!text || !state.order.includes(id) || !canWork(personId)) return false;
+ append(agent, "user", text, personId);
+ announce(personName(personId) + " sent a prompt to " + agent.name + ".");
+ agent.demoInputs.push(text);
+ if (agent.status !== "working") simulateNextTurn(agent);
+ render();
+ return true;
+ }
+
+ // A tiny fake engine so the prototype responds. Real agents own their existing input behavior.
+ // The shared composer always sends; it has no controller or collaboration queue UI.
+ function simulateNextTurn(agent) {
+ const text = agent.demoInputs.shift();
+ if (!text) return;
+ agent.status = "working";
+ agent.run = ++runSequence;
+ const run = agent.run;
+ const test = /test|regression|verify/i.test(text);
+ const steps = test
+ ? ["Checking the test setup…", "$ pnpm test -- auth", "Demo result: 3 tests passed. Ready for review."]
+ : ["Inspecting the relevant files…", "Preparing a change and checking the result…", "Demo result: work prepared. Ready for your next instruction."];
+ steps.forEach((line, i) => schedule(() => {
+ if (agent.run !== run || agent.status !== "working") return;
+ append(agent, i === steps.length - 1 ? "result" : "agent", line);
+ if (i === steps.length - 1) {
+ agent.status = "idle";
+ simulateNextTurn(agent);
+ }
+ render();
+ }, [450, 1450, 3000][i]));
+ }
+
+ function removePane(personId, id) {
+ if (!canWork(personId) || !state.order.includes(id)) return;
+ const agent = state.agents[id];
+ const index = state.order.indexOf(id);
+ state.removed.push({ id, index });
+ state.order.splice(index, 1);
+ if (state.maximized === id) state.maximized = null;
+ announce(personName(personId) + " removed " + agent.name + " for everyone. The agent keeps running.");
+ render();
+ }
+
+ function act(action, personId, id) {
+ const agent = state.agents[id];
+ if (action === "join") {
+ member(personId).joined = true;
+ announce(personName(personId) + " joined " + state.name + ".");
+ render();
+ return;
+ }
+ if (action === "share") {
+ if (member(personId)?.role !== "owner") return;
+ renderMembers();
+ $("#invite-error").textContent = "";
+ $("#share-dialog").showModal();
+ return;
+ }
+ if (!canWork(personId)) return;
+ if (id && !state.order.includes(id)) return;
+ if (action === "add") {
+ const newId = "agent-" + nextAgent++;
+ const name = "Agent " + (nextAgent - 1);
+ state.agents[newId] = createAgent(newId, name, "Codex", personName(personId) + "’s machine");
+ state.order.push(newId);
+ state.maximized = null;
+ announce(personName(personId) + " added " + name + " for everyone.");
+ } else if (action === "restore") state.maximized = null;
+ else if (action === "undo") {
+ const removed = state.removed.pop();
+ if (!removed || state.order.includes(removed.id)) return;
+ state.order.splice(Math.min(removed.index, state.order.length), 0, removed.id);
+ announce(personName(personId) + " restored " + state.agents[removed.id].name + " for everyone.");
+ } else if (action === "remove") {
+ removePane(personId, id);
+ return;
+ } else if (action === "up" || action === "down") {
+ const index = state.order.indexOf(id);
+ const next = index + (action === "up" ? -1 : 1);
+ if (next < 0 || next >= state.order.length) return;
+ [state.order[index], state.order[next]] = [state.order[next], state.order[index]];
+ announce(personName(personId) + " moved " + agent.name + " " + action + " for everyone.");
+ } else if (action === "size") {
+ agent.size = agent.size === "large" ? "small" : "large";
+ announce(personName(personId) + " resized " + agent.name + " for everyone.");
+ } else if (action === "maximize") {
+ state.maximized = state.maximized === id ? null : id;
+ announce(state.maximized ? personName(personId) + " maximized " + agent.name + " for everyone." : "All agents are visible again.");
+ } else if (action === "interrupt" && agent.status === "working") {
+ agent.run = ++runSequence;
+ agent.status = "idle";
+ agent.demoInputs = [];
+ append(agent, "system", personName(personId) + " stopped the agent.");
+ announce(personName(personId) + " stopped " + agent.name + ".");
+ }
+ render();
+ }
+
+ function renderMembers() {
+ const list = $("#member-list");
+ list.replaceChildren();
+ for (const person of state.members) {
+ const row = element("div", "member");
+ row.append(element("span", "member-name", person.name + (person.joined ? "" : " · invited")));
+ if (person.role === "owner") row.append(element("span", "member-role", "Owner"));
+ else {
+ const select = element("select");
+ select.setAttribute("aria-label", person.name + " permission");
+ for (const [value, label] of [["editor", "Can work"], ["viewer", "Can view"]]) {
+ const option = element("option", "", label); option.value = value; select.append(option);
+ }
+ select.value = person.role;
+ select.addEventListener("change", () => {
+ person.role = select.value;
+ announce(person.name + " now has " + (person.role === "viewer" ? "view" : "work") + " access.");
+ render();
+ });
+ row.append(select);
+ }
+ list.append(row);
+ }
+ }
+ $("#invite-form").addEventListener("submit", event => {
+ event.preventDefault();
+ const name = $("#invite-name").value.trim();
+ if (!name) return;
+ if (state.members.some(person => person.name.toLowerCase() === name.toLowerCase())) {
+ $("#invite-error").textContent = "That person is already in this demo.";
+ return;
+ }
+ const person = { id: "person-" + state.members.length, name, role: $("#invite-role").value, joined: false };
+ state.members.push(person);
+ rightPerson = person.id;
+ $("#invite-name").value = "";
+ $("#share-dialog").close();
+ announce("Owner invited " + name + " to " + state.name + ".");
+ render();
+ });
+ $$("[data-close-dialog]").forEach(control => control.addEventListener("click", () => control.closest("dialog").close()));
+ $("#teammate-select").addEventListener("change", event => { rightPerson = event.target.value; render(); });
+ $("#reset-demo").addEventListener("click", reset);
+ reset();
+})();
diff --git a/docs/prototypes/collaboration/comments.js b/docs/prototypes/collaboration/comments.js
new file mode 100644
index 000000000..b591d14dc
--- /dev/null
+++ b/docs/prototypes/collaboration/comments.js
@@ -0,0 +1,283 @@
+// Comments belong to saved transcript passages, not terminal screen coordinates.
+// This prototype uses DOM ranges; a real terminal would supply its selected text.
+function createPaneComments({ views, viewPerson, canWork, personName, getAgent, announce, render }) {
+ const panels = new Map();
+ const popup = document.querySelector("#selection-comment");
+ let selection = null;
+ let nextThread = 1;
+
+ function node(tag, className, text) {
+ const result = document.createElement(tag);
+ if (className) result.className = className;
+ if (text !== undefined) result.textContent = text;
+ return result;
+ }
+ function action(label, handler, title) {
+ const result = node("button", "", label);
+ result.type = "button";
+ if (title) result.setAttribute("aria-label", title);
+ result.addEventListener("click", handler);
+ return result;
+ }
+ function uiFor(view, agent) {
+ const key = view.root.dataset.client + ":" + viewPerson(view) + ":" + agent.id;
+ if (!panels.has(key)) panels.set(key, {
+ open: agent.threads.length > 0, active: agent.threads[0]?.id,
+ anchor: null, text: "", replies: new Map()
+ });
+ return panels.get(key);
+ }
+ function speaker(agent, entry) {
+ return entry.kind === "user" ? personName(entry.sender) + "’s prompt" : agent.engine + " output";
+ }
+ function thread(anchors, author, text) {
+ return { id: "thread-" + nextThread++, anchors,
+ quote: anchors.map(anchor => anchor.text).join("\n"),
+ comments: [{ author, text, time: Date.now() }] };
+ }
+ function seed(agent, entry, author, text) {
+ agent.threads.push(thread([{ entryId: entry.id, start: 0, end: entry.text.length,
+ text: entry.text, speaker: speaker(agent, entry) }], author, text));
+ agent.commentVersion++;
+ }
+ function open(view, agent, id) {
+ const ui = uiFor(view, agent);
+ ui.open = true;
+ ui.active = id;
+ render();
+ const pane = view.panes.get(agent.id);
+ pane?.querySelector('[data-thread="' + id + '"]')?.scrollIntoView({ block: "nearest" });
+ }
+ function toggle(view, agent) {
+ const ui = uiFor(view, agent);
+ ui.open = !ui.open;
+ render();
+ }
+ function buildPanel() {
+ return node("aside", "comments-panel");
+ }
+
+ function markPassages(pane, agent) {
+ // Only touch transcript text when a new annotation is added, so live output
+ // and replies do not disturb text selection, scroll position, or a draft.
+ if (pane.annotationVersion !== agent.commentVersion) {
+ for (const entry of agent.log) {
+ const body = pane.querySelector('[data-entry="' + entry.id + '"] .entry-text');
+ if (!body) continue;
+ const anchors = agent.threads.flatMap(item => item.anchors
+ .filter(anchor => anchor.entryId === entry.id)
+ .map(anchor => ({ ...anchor, threadId: item.id })));
+ const cuts = [...new Set([0, entry.text.length, ...anchors.flatMap(a => [a.start, a.end])])].sort((a, b) => a - b);
+ const fragments = [];
+ for (let i = 1; i < cuts.length; i++) {
+ const start = cuts[i - 1], end = cuts[i];
+ const text = entry.text.slice(start, end);
+ const ids = anchors.filter(a => a.start < end && a.end > start).map(a => a.threadId);
+ if (!ids.length) fragments.push(document.createTextNode(text));
+ else {
+ const mark = node("mark", "comment-anchor", text);
+ mark.dataset.threads = [...new Set(ids)].join(" ");
+ // Keep annotated text natively selectable. The pane's Comments
+ // button provides keyboard access to these same threads.
+ mark.title = "Open comments on this passage";
+ fragments.push(mark);
+ }
+ }
+ body.replaceChildren(...fragments);
+ }
+ pane.annotationVersion = agent.commentVersion;
+ }
+ }
+
+ function quoteBlock(anchors) {
+ const group = node("div", "comment-context");
+ group.append(node("div", "quote-source", anchors.length === 1 ? anchors[0].speaker : "Selected passages"),
+ node("blockquote", "comment-quote", anchors.map(anchor => anchor.text).join("\n")));
+ return group;
+ }
+ function composer(label, value, save, submit) {
+ const form = node("form", "comment-form");
+ const input = node("textarea");
+ input.placeholder = label;
+ input.setAttribute("aria-label", label);
+ input.rows = 2;
+ input.maxLength = 4000;
+ input.value = value;
+ const send = node("button", "", label === "Add a comment" ? "Comment" : "Reply");
+ send.type = "submit";
+ send.disabled = !value.trim();
+ input.addEventListener("input", () => { save(input.value); send.disabled = !input.value.trim(); });
+ form.addEventListener("submit", event => {
+ event.preventDefault();
+ if (input.value.trim()) submit(input.value.trim());
+ });
+ form.append(input, send);
+ return form;
+ }
+
+ function renderPane(view, pane, agent) {
+ const ui = uiFor(view, agent);
+ const writable = canWork(viewPerson(view));
+ const panel = pane.querySelector(".comments-panel");
+ const toggle = pane.querySelector('[data-action="comments"]');
+ toggle.textContent = "Comments" + (agent.threads.length ? " " + agent.threads.length : "");
+ toggle.setAttribute("aria-label", "Comments on " + agent.name + ": " + agent.threads.length);
+ toggle.setAttribute("aria-expanded", String(ui.open));
+ panel.hidden = !ui.open;
+ panel.setAttribute("aria-label", "Comments on " + agent.name);
+ pane.classList.toggle("has-comments", ui.open);
+ markPassages(pane, agent);
+ for (const mark of pane.querySelectorAll(".comment-anchor")) {
+ mark.classList.toggle("active-anchor", ui.open && mark.dataset.threads.split(" ").includes(ui.active));
+ }
+ if (!pane.commentEventsBound) {
+ pane.commentEventsBound = true;
+ function visit(event) {
+ const mark = event.target.closest(".comment-anchor");
+ if (!mark || !window.getSelection()?.isCollapsed) return;
+ open(view, agent, mark.dataset.threads.split(" ")[0]);
+ }
+ pane.addEventListener("click", visit);
+ }
+ const signature = JSON.stringify([viewPerson(view), ui.open, ui.active, ui.anchor, writable,
+ agent.threads.map(item => [item.id, item.comments.length])]);
+ if (panel.signature === signature) return;
+ panel.signature = signature;
+ const focused = panel.contains(document.activeElement) && document.activeElement.tagName === "TEXTAREA"
+ ? { key: document.activeElement.dataset.draft, start: document.activeElement.selectionStart, end: document.activeElement.selectionEnd } : null;
+ const oldScroll = panel.querySelector(".thread-list")?.scrollTop || 0;
+ panel.replaceChildren();
+ const header = node("div", "comments-heading");
+ header.append(node("strong", "", "Comments"), action("×", () => { ui.open = false; render(); }, "Close comments"));
+ panel.append(header);
+ const list = node("div", "thread-list");
+ if (ui.anchor && writable) {
+ const draft = node("div", "thread-card new-comment");
+ draft.append(quoteBlock(ui.anchor));
+ const form = composer("Add a comment", ui.text, text => { ui.text = text; }, text => {
+ if (!canWork(viewPerson(view))) return;
+ const item = thread(ui.anchor, viewPerson(view), text);
+ agent.threads.push(item);
+ agent.commentVersion++;
+ ui.anchor = null;
+ ui.text = "";
+ ui.active = item.id;
+ announce(personName(viewPerson(view)) + " commented on " + agent.name + ".");
+ render();
+ });
+ form.querySelector("textarea").dataset.draft = "new";
+ form.append(action("Cancel", () => { ui.anchor = null; ui.text = ""; render(); }));
+ draft.append(form);
+ list.append(draft);
+ }
+ for (const item of agent.threads) {
+ const card = node("article", "thread-card" + (ui.active === item.id ? " active-thread" : ""));
+ card.dataset.thread = item.id;
+ card.append(quoteBlock(item.anchors));
+ card.addEventListener("click", event => {
+ if (ui.active !== item.id && !event.target.closest("button, textarea")) open(view, agent, item.id);
+ });
+ for (const comment of item.comments) {
+ const entry = node("div", "comment-entry");
+ const metadata = node("div", "comment-meta");
+ metadata.append(node("strong", "", personName(comment.author)),
+ node("time", "", new Date(comment.time).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })));
+ entry.append(metadata, node("p", "", comment.text));
+ card.append(entry);
+ }
+ if (writable && ui.active === item.id) {
+ const form = composer("Reply to thread", ui.replies.get(item.id) || "", text => ui.replies.set(item.id, text), text => {
+ if (!canWork(viewPerson(view))) return;
+ item.comments.push({ author: viewPerson(view), text, time: Date.now() });
+ ui.replies.delete(item.id);
+ announce(personName(viewPerson(view)) + " replied on " + agent.name + ".");
+ render();
+ });
+ form.querySelector("textarea").dataset.draft = item.id;
+ card.append(form);
+ } else if (writable) card.append(action("Reply", () => open(view, agent, item.id)));
+ list.append(card);
+ }
+ if (!agent.threads.length && !ui.anchor) list.append(node("p", "comments-empty",
+ writable ? "Highlight text in a prompt or agent output, then click Comment." : "No comments yet."));
+ panel.append(list, node("p", "comments-note", "Shared with teammates. Comments aren’t sent to the agent."));
+ list.scrollTop = oldScroll;
+ if (focused) {
+ const input = panel.querySelector('[data-draft="' + focused.key + '"]');
+ input?.focus({ preventScroll: true });
+ input?.setSelectionRange(focused.start, focused.end);
+ }
+ }
+
+ function readSelection() {
+ const selected = window.getSelection();
+ selection = null;
+ popup.hidden = true;
+ if (!selected?.rangeCount || selected.isCollapsed) return;
+ const range = selected.getRangeAt(0);
+ const parent = value => value.nodeType === Node.ELEMENT_NODE ? value : value.parentElement;
+ const transcript = parent(range.startContainer)?.closest(".transcript");
+ if (!transcript || parent(range.endContainer)?.closest(".transcript") !== transcript) return;
+ const view = views.find(candidate => candidate.root.contains(transcript));
+ if (!view || !canWork(viewPerson(view))) return;
+ const agent = getAgent(transcript.closest("[data-agent]").dataset.agent);
+ const anchors = [];
+ for (const body of transcript.querySelectorAll(".entry-text")) {
+ if (!range.intersectsNode(body)) continue;
+ const part = document.createRange();
+ part.selectNodeContents(body);
+ if (body.contains(range.startContainer)) part.setStart(range.startContainer, range.startOffset);
+ if (body.contains(range.endContainer)) part.setEnd(range.endContainer, range.endOffset);
+ const text = part.toString();
+ if (!text.trim()) continue;
+ const prefix = document.createRange();
+ prefix.selectNodeContents(body);
+ prefix.setEnd(part.startContainer, part.startOffset);
+ const start = prefix.toString().length;
+ const entry = agent.log.find(item => item.id === body.closest("[data-entry]").dataset.entry);
+ anchors.push({ entryId: entry.id, start, end: start + text.length, text, speaker: speaker(agent, entry) });
+ }
+ if (!anchors.length) return;
+ selection = { view, agent, anchors };
+ const rects = range.getClientRects();
+ const rect = rects[rects.length - 1] || range.getBoundingClientRect();
+ popup.style.left = Math.max(8, Math.min(rect.right - 40, window.innerWidth - 110)) + "px";
+ popup.style.top = Math.max(8, Math.min(rect.bottom + 6, window.innerHeight - 42)) + "px";
+ popup.hidden = false;
+ }
+ function startComment() {
+ if (!selection || !canWork(viewPerson(selection.view))) return;
+ const { view, agent, anchors } = selection;
+ const ui = uiFor(view, agent);
+ ui.open = true;
+ ui.anchor = anchors;
+ ui.active = null;
+ // Keep an unfinished comment if the writer changes their selected passage.
+ selection = null;
+ popup.hidden = true;
+ window.getSelection()?.removeAllRanges();
+ render();
+ const panel = view.panes.get(agent.id)?.querySelector(".comments-panel");
+ panel?.querySelector(".new-comment textarea")?.focus();
+ }
+ popup.addEventListener("mousedown", event => event.preventDefault());
+ popup.addEventListener("click", startComment);
+ document.addEventListener("selectionchange", readSelection);
+ document.addEventListener("pointerup", readSelection);
+ document.addEventListener("keydown", event => {
+ if ((event.metaKey || event.ctrlKey) && event.altKey && event.key.toLowerCase() === "m" && selection) {
+ event.preventDefault();
+ startComment();
+ }
+ });
+ window.addEventListener("scroll", () => { popup.hidden = true; }, true);
+ window.addEventListener("resize", () => { popup.hidden = true; });
+
+ return { seed, toggle, buildPanel, renderPane, reset() {
+ panels.clear();
+ selection = null;
+ nextThread = 1;
+ popup.hidden = true;
+ window.getSelection()?.removeAllRanges();
+ } };
+}
diff --git a/docs/prototypes/collaboration/index.html b/docs/prototypes/collaboration/index.html
new file mode 100644
index 000000000..96246dc5b
--- /dev/null
+++ b/docs/prototypes/collaboration/index.html
@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Harness — shared swarm prototype</title>
+ <link rel="stylesheet" href="./styles.css">
+ <script src="./comments.js" defer></script>
+ <script src="./app.js" defer></script>
+</head>
+<body>
+ <header class="prototype-header">
+ <div>
+ <h1>Shared swarm</h1>
+ <p>Highlight a prompt or agent output → Comment → reply from the other view.</p>
+ <p>Local simulation. No real agents or commands.</p>
+ </div>
+ <button id="reset-demo" type="button">Reset demo</button>
+ </header>
+ <main class="clients">
+ <section class="client" data-client="left" aria-label="Your view">
+ <div class="view-label"><strong>Your view</strong><span>Owner</span></div>
+ <div class="workspace"></div>
+ </section>
+ <section class="client" data-client="right" aria-label="Teammate view">
+ <label class="view-label" for="teammate-select"><strong>Teammate’s view</strong><select id="teammate-select"></select></label>
+ <div class="workspace"></div>
+ </section>
+ </main>
+ <dialog id="share-dialog">
+ <header class="dialog-header"><h2>Share swarm</h2><button type="button" data-close-dialog aria-label="Close sharing">×</button></header>
+ <div id="member-list"></div>
+ <form id="invite-form">
+ <label for="invite-name">Invite someone</label>
+ <div class="invite-row">
+ <input id="invite-name" name="name" placeholder="Name" required maxlength="32" autocomplete="off">
+ <select id="invite-role" name="role" aria-label="Invitation permission">
+ <option value="editor">Can work</option>
+ <option value="viewer">Can view</option>
+ </select>
+ </div>
+ <p class="hint">The invitation appears in the teammate view for you to try.</p>
+ <p id="invite-error" class="error" role="alert"></p>
+ <button type="submit">Invite</button>
+ </form>
+ </dialog>
+ <button id="selection-comment" type="button" hidden>Comment</button>
+ <div id="announcement" class="sr-only" role="status" aria-live="polite"></div>
+</body>
+</html>
diff --git a/docs/prototypes/collaboration/styles.css b/docs/prototypes/collaboration/styles.css
new file mode 100644
index 000000000..7add6b22b
--- /dev/null
+++ b/docs/prototypes/collaboration/styles.css
@@ -0,0 +1,103 @@
+:root { color-scheme: light; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: #29252a; background: #f4f3f4; font-size: 14px; }
+* { box-sizing: border-box; }
+body { margin: 0; padding: 20px; }
+button, input, select, textarea { font: inherit; }
+button { border: 1px solid #cfc9cf; border-radius: 4px; padding: 6px 9px; background: #fff; color: inherit; cursor: pointer; }
+button:hover:not(:disabled) { background: #f0edf1; }
+button:disabled { opacity: .4; cursor: default; }
+input, select, textarea { min-width: 0; border: 1px solid #cfc9cf; border-radius: 4px; background: #fff; color: inherit; padding: 7px; }
+button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-visible { outline: 2px solid #785c7c; outline-offset: 2px; }
+[hidden] { display: none !important; }
+h1 { font-size: 20px; font-weight: 600; margin: 0 0 5px; }
+h2 { font-size: 17px; margin: 0; }
+p { line-height: 1.5; }
+.prototype-header { max-width: 1680px; margin: 0 auto 22px; display: flex; justify-content: space-between; align-items: center; gap: 18px; }
+.prototype-header p { margin: 0; color: #706871; font-size: 12px; }
+.clients { max-width: 1680px; margin: auto; display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 22px; align-items: start; }
+.client { min-width: 0; }
+.view-label { display: flex; align-items: center; justify-content: space-between; gap: 12px; min-height: 34px; margin-bottom: 9px; font-size: 13px; }
+.view-label > span { color: #706871; }
+.view-label select { font-size: 12px; padding: 4px 7px; }
+.workspace { border: 1px solid #cbc5cc; border-radius: 6px; background: #eae6eb; overflow: hidden; }
+.swarm-header { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 10px; padding: 12px; background: #463746; color: #fff; }
+.swarm-title { flex: 1; min-width: 100px; width: 150px; border-color: transparent; background: transparent; color: inherit; font-weight: 600; padding: 4px 5px; }
+.swarm-title:focus { background: #fff; color: #29252a; }
+.swarm-title:disabled { opacity: 1; }
+.swarm-tools { display: flex; gap: 6px; flex-wrap: wrap; }
+.swarm-tools button { font-size: 12px; color: #29252a; }
+.presence { padding: 8px 12px; background: #fff; border-bottom: 1px solid #d8d2da; color: #645b66; font-size: 12px; }
+.notice { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 8px; padding: 7px 12px; border-bottom: 1px solid #d8d2da; background: #f6f0de; color: #64552b; font-size: 12px; min-height: 36px; }
+.notice button { font-size: 12px; padding: 3px 7px; }
+.agent-grid { padding: 10px; display: flex; flex-direction: column; gap: 10px; }
+.agent { min-width: 0; background: #fff; border: 1px solid #cfc8d1; border-radius: 4px; overflow: hidden; }
+.agent-header { padding: 8px 9px; display: flex; align-items: center; gap: 8px; background: #f5f2f6; border-bottom: 1px solid #e0dbe1; }
+.agent-heading { min-width: 0; flex: 1; }
+.agent-name { width: 100%; background: transparent; border: 1px solid transparent; font-weight: 600; font-size: 13px; padding: 2px; }
+.agent-name:focus { background: white; border-color: #cfc9cf; }
+.agent-name:disabled { opacity: 1; }
+.agent-meta { padding: 2px; color: #706871; font-size: 11px; overflow-wrap: anywhere; }
+.pane-tools { display: flex; gap: 3px; }
+.pane-tools button { padding: 3px 5px; min-width: 25px; min-height: 26px; font-size: 13px; }
+.control-bar { display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 6px 10px; border-bottom: 1px solid #ece8ed; min-height: 36px; font-size: 12px; }
+.control-label { color: #6a606c; }
+.control-actions { display: flex; gap: 5px; }
+.control-actions button { font-size: 11px; padding: 4px 7px; }
+.pane-conversation { display: grid; grid-template-columns: minmax(0, 1fr); }
+.has-comments .pane-conversation { grid-template-columns: minmax(0, 1fr) 260px; }
+.agent-main { min-width: 0; display: flex; flex-direction: column; }
+.transcript { height: 140px; overflow: auto; padding: 11px 12px; font: 12px/1.6 "SFMono-Regular", Menlo, Consolas, monospace; background: #fff; }
+.agent-main .transcript { flex: 1 1 auto; min-height: 140px; }
+.agent.large .transcript { height: 260px; }
+.agent.maximized .transcript { height: 460px; }
+.entry { margin-bottom: 8px; overflow-wrap: anywhere; white-space: pre-wrap; }
+.entry:last-child { margin-bottom: 0; }
+.entry .sender { font-weight: 600; color: #77517d; }
+.entry-system { color: #827684; font-size: 11px; }
+.entry-result { color: #246542; }
+.comment-anchor { color: inherit; background: #fff0b8; box-shadow: inset 0 -1px #d5ab3d; cursor: pointer; user-select: text; }
+.comment-anchor.active-anchor { background: #ffe191; }
+.comment-anchor:focus-visible { outline: 2px solid #785c7c; }
+#selection-comment { position: fixed; z-index: 10; border-color: #a68a35; background: #fff6d4; box-shadow: 0 2px 8px #29252a26; }
+.comments-panel { min-width: 0; border-left: 1px solid #e0dbe1; background: #faf9f6; font-size: 12px; display: flex; flex-direction: column; }
+.comments-heading { display: flex; align-items: center; justify-content: space-between; padding: 8px 10px; border-bottom: 1px solid #e0dbe1; }
+.comments-heading button { padding: 1px 6px; font-size: 16px; }
+.thread-list { min-height: 0; max-height: 320px; overflow: auto; padding: 8px; flex: 1; }
+.thread-card { background: #fff; border: 1px solid #ded8cc; border-radius: 4px; padding: 10px; margin-bottom: 8px; }
+.thread-card:last-child { margin-bottom: 0; }
+.thread-card.active-thread, .thread-card.new-comment { border-color: #c9a446; }
+.comment-context { margin-bottom: 11px; }
+.quote-source { color: #776e60; font-size: 10px; margin-bottom: 5px; }
+.comment-quote { margin: 0; padding-left: 8px; border-left: 2px solid #d5ab3d; color: #665836; white-space: pre-wrap; overflow-wrap: anywhere; max-height: 95px; overflow: auto; line-height: 1.5; }
+.comment-entry { margin: 10px 0; }
+.comment-meta { display: flex; justify-content: space-between; gap: 10px; font-size: 11px; }
+.comment-meta time { color: #8b8377; white-space: nowrap; }
+.comment-entry p { margin: 4px 0 0; white-space: pre-wrap; overflow-wrap: anywhere; }
+.comment-form { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 6px; }
+.comment-form textarea { width: 100%; font-size: 12px; min-height: 55px; resize: vertical; }
+.comment-form button { padding: 4px 8px; font-size: 11px; }
+.comments-empty { margin: 5px; color: #786f64; }
+.comments-note { font-size: 10px; color: #786f64; margin: 0; padding: 8px 10px; border-top: 1px solid #e0dbe1; }
+.prompt-form { display: flex; gap: 7px; align-items: flex-end; border-top: 1px solid #e0dbe1; padding: 8px; background: #faf9fb; }
+.prompt-form textarea { flex: 1; min-height: 44px; height: 44px; resize: none; font-size: 12px; line-height: 1.35; }
+.prompt-form button { font-size: 12px; min-height: 32px; }
+.empty, .join-screen { padding: 35px 20px; text-align: center; }
+.join-screen p { color: #706871; }
+dialog { width: min(450px, calc(100% - 32px)); border: 1px solid #bfb6c2; border-radius: 6px; padding: 20px; color: inherit; }
+dialog::backdrop { background: #22152640; }
+.dialog-header, .dialog-actions { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.dialog-header { margin-bottom: 17px; }
+.dialog-actions { justify-content: flex-end; margin-top: 20px; }
+.member { display: flex; align-items: center; gap: 12px; margin: 12px 0; }
+.member-name { flex: 1; overflow-wrap: anywhere; }
+.member-role { color: #706871; }
+#invite-form { margin-top: 22px; padding-top: 17px; border-top: 1px solid #e0dbe1; }
+#invite-form label { display: block; margin-bottom: 8px; }
+.invite-row { display: flex; gap: 8px; }
+.invite-row input { flex: 1; width: 0; }
+.hint { font-size: 12px; color: #706871; }
+.error { color: #9c2d37; font-size: 12px; }
+.error:empty { display: none; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+@media (max-width: 900px) { .clients { grid-template-columns: minmax(0, 1fr); } body { padding: 12px; } }
+@media (min-width: 901px) and (max-width: 1400px), (max-width: 600px) { .has-comments .pane-conversation { grid-template-columns: minmax(0, 1fr); } .comments-panel { border-left: 0; border-top: 1px solid #e0dbe1; } }
+@media (max-width: 450px) { .prototype-header { align-items: flex-start; } .prototype-header button { flex-shrink: 0; font-size: 12px; } .agent-header { flex-wrap: wrap; } .pane-tools { margin-left: auto; } .invite-row { flex-direction: column; } .invite-row input { width: 100%; } .control-bar { flex-wrap: wrap; } .agent.maximized .transcript { height: 300px; } }