Threads

Draft for review

A thread is a shared place where people and agents work on one goal. The conversation, the agents' runs, the documents being written (artifacts), the approvals the work needs and the decisions made all sit together in it, so anyone who joins later can read what happened and why.

This guide describes threads as they work today on the golive branch. What is not possible yet is listed at the end.

Threads or a conversation with an agent#

The Threads page has two parts.

• Talk to an agent lists the agents you work with. Clicking one opens Conversation with : a private thread between you and that agent. Use it when you want one agent to do one thing for you.
• Your threads lists every thread you take part in, newest activity first. A thread has a goal and several participants. Use one when more than one person or agent is involved, when someone has to sign off, or when the work produces a document that will go through versions.

A conversation has no artifacts, no Close button, no participants to manage and no @ list. Everything else below is about threads.

Starting a thread#

Open Threads and choose New thread.

You are always the thread's owner. A template's owner slot (for example the roadmap's product manager) is filled by you and is not shown; the line under the template says so ("You are its product manager and its owner") and whether an approver signs off before it closes.

Each slot says what it is for: "signs off before it closes" (an approver), "takes part" (a contributor) or "reads only" (an observer). A slot lists only who may fill it:

• A person slot (Engineering lead, Reviewer) lists people.
• An agent slot (Product agent) lists only the agents you work with.
• An open slot (Author, Responder) lists people, then Agents you work with.

Some agent slots start filled: Roadmap planning picks Product Agent and Analyst Agent, Release picks Release-notes writer, Customer ticket picks Support Agent, as long as you work with that agent. Change them if you like. Someone already chosen for one slot shows as "(in another role)" in the others and cannot be picked twice.

Create stays greyed out until the thread has a goal and every slot is filled; the line above it says what is missing ("Choose someone for Engineering lead").

Participants and roles#

On a wide screen the participants, approvals, artifacts, decisions and tasks sit in the right-hand panel. On a phone, open them with Details.

An observer, or an admin who is not in the thread, sees the conversation and the details but no message box. In its place:

• Observer: "You are an observer here: you can read this thread, but not post, ask its agents or edit its artifacts."
• Admin not in the thread: "You can read this thread but you are not in it, so you cannot post in it. Its owner, , can add you."

Notes:

• Contributors can propose in a message, but only owners and approvers record decisions.
• Each person or agent appears once in a thread, at one role. If the same person is named twice when the thread is made, they keep the higher role.
• A thread approver is not the same as the approver of an approval card. Who approves an agent's action (a refund, an email) is set by the company's policy, not by the thread. In the demo, a refund asked of the Churn-risk watcher in Maya's thread waits for Ada, who is not in the thread, and a thread participant who tries to decide it is refused. Whether a thread's approver should decide the approval cards in that thread is an open product decision.

Adding and removing people#

The owner sees Add people above the participant list.

1. Choose Add people (on a phone the details panel closes first).
2. Search and tick people, and agents you work with. Anyone already in the thread is left out of the list.
3. Pick one role for everyone you ticked: Contributor, Approver or Observer.
4. Choose Add. A note confirms "Added Eli Novak", and each person added gets an inbox item ("Pat Kim added you to 'Q1 roadmap' as observer"). People chosen when the thread is made get no such item.

To remove someone, the owner presses the ✕ on their row and confirms. The confirmation says what it means: they can no longer read or post in the thread, and a mention does not bring them back. The owner can add them again later.

Rules the screen and the server both keep:

• Only the owner adds or removes, and the owner cannot remove themself.
• You can add only agents you work with (agents that act for you).
• On a thread whose template needs approval to close (Roadmap planning, Review, Release):
  • the approver must be a person; adding an agent as approver is refused;
  • the last approver cannot be removed or demoted. The refusal says: "Erin Walsh is the only approver of this Roadmap planning thread, which closes once an approver has logged a decision. Add another approver first, or ask Erin Walsh to log a decision and close it."
• Nobody can be added to a closed thread.

People also join a thread without the owner adding them: see Mentions and asking an agent.

The message box#

At the bottom of an open thread, for owners, approvers and contributors:

When Ask agent is greyed out, hovering it says why:

A thread with no agents says "No agents in this thread yet. Mention one with @ to bring it in", and for the owner "or use Add people in Details".

Asking runs the agent on your behalf, and only with what you have delegated to it. An agent that was not yet in the thread joins it as a contributor, so its answer lands there. If its plan needs an approval, the run pauses and an approval card appears in the thread (see Approvals).

In the demo there is no model unless you set a key: an asked agent answers with a note that the demo's stub planner only knows the walkthrough's asks in demo.md.

Mentioning people and agents#

Type @ in the message box. A list opens with, in order: In this thread, People, then Agents you work with. Keep typing to narrow it (it matches any part of a name, so @er also offers Tom Becker). Use the arrow keys and Enter or Tab, or click, to pick; Escape closes the list. The name goes into the text as @Erin Walsh.

You can also type a mention by hand: @Erin Walsh or the id @erin both work. The message then shows "to " and the mentions are highlighted.

What a mention does:

Any owner, approver or contributor can mention, so a contributor can bring a person or an agent into the thread this way. Only the owner can remove them again.

When an agent is mentioned:

• It runs for the person who posted, and only with what that person has delegated to it. If the agent holds no delegation from you, nothing runs and it does not join: its team lead gets an inbox item saying you mentioned it, and the thread shows nothing.
• It wakes on the next clock tick (within half a minute in the demo) and its reply lands in the thread. Ask agent starts the run at once instead.
• A second mention while its task is still open adds to that task instead of starting another.
• An agent whose module is paused does not run; the thread gets a note saying it is paused.

Agents can mention each other too, but only a few times in a row (the thread's chatter cap: 4 by default). After that, agents are refused until a person posts or an artifact changes, and the owner is told the thread has stalled.

Artifacts and versions#

An artifact is a document the thread works on: a roadmap, a reply draft, a table. Templates create theirs up front, empty.

• Create: New artifact, give it a name and a kind. It starts empty at version 1.
• Edit: press Edit on the artifact, change the text, say what changed, and choose Save new version. Every save is a new version; nothing is overwritten. Observers and people not in the thread see no Edit button.
• History: the version list on each artifact shows every version as v2 · Erin Walsh · SSO and audit log. Pick one to see it.
• Agents write artifacts too: when an agent's run produces one with the same name, it becomes the next version. Each new version also appears in the conversation as "updated to v2".
• The thread owner is told (in the inbox) of every new version someone else makes.

Plain text is saved as text. Text that is valid JSON is saved as structured content; a roadmap written as {"items": [{"title": "SSO", "quarter": "Q1"}]} shows as a list of items.

Once a thread is closed its artifacts can still be read, version by version, but not edited.

Approvals in a thread#

When an agent asked in a thread wants to do something the company's policy holds for a person (a refund over the cap, an email to a customer), its run pauses. The thread shows an approval card from the agent with what it wants to do, the amounts, why it needs approval and who it is waiting for. The same approval is listed under Approvals in the details, and the approver gets it in their inbox.

Everyone who can see the thread sees the card. Only the named approver can decide it; anyone else who tries is refused. Once approved, the run carries on and its result lands in the thread.

Decisions#

Log decision records a decision with its reason and topics. It appears in the conversation as a decision card, under Decisions in the details, on the company's decisions list, and in the company knowledge agents read, so they stop asking the same question again.

Only owners and approvers log decisions. A decision cannot be edited or withdrawn.

Closing a thread#

Close thread (top right) ends the thread after a confirmation ("Close this thread? Nobody can post in it afterwards."). Nobody can post, ask, decide, edit artifacts or add people afterwards, and it shows a closed badge. Everything stays readable. A closed thread cannot be reopened.

Until an approver has logged a decision, the owner's button is greyed out and the head reads "Waiting for Erin Walsh to log a decision" (every approver is named). The owner's own decision does not count. As soon as an approver logs one, the owner's button works.

Admins who are not the owner or an approver do not see the button.

Conversations with an agent cannot be closed; start a new one with New conversation instead.

Who can see what#

• A thread is visible to its owner and participants, to anyone escalated to from it, and to admins. Anyone else who opens its link gets "not found". Someone mentioned joins the thread, so they can read it.
• Someone the owner removed cannot read the thread any more, even from an older inbox item, until the owner adds them again.
• Approvals in the thread are visible to everyone who can see the thread.
• Decisions also become company knowledge that others may read even without seeing the thread.

Templates#

A slot is pre-filled only if you work with that agent. A module's template shows only while the module is installed. Templates the system uses itself, such as the context module's Team context, are not offered.

Not possible yet#

• Reopening a closed thread.
• Editing or withdrawing a decision.
• Renaming a thread or changing its goal.
• Changing a thread's budget.
• Changing someone's role from the screen. Add people leaves out anyone already in the thread; to change a role, remove the person and add them again with the new role, or use the API (below).
• Handing the thread to another owner, or leaving a thread you are in (only the owner removes people).
• Mentioning in a brand-new conversation with an agent: the @ list appears only once the conversation exists.
• A thread approver deciding the approval cards in their thread (an open product decision; see Participants and roles).

For developers#

API#

All under /api, with Authorization: Bearer <token>. A thread the caller may not see answers 404.

Adding, removing (and changing a role) and closing are governed as the action thread.manage (risk low), so a policy rule can hold or refuse them like any other action; an approved change is checked again when it is made.

Errors from these routes:

There is no route to reopen a thread, rename it, change its budget or edit a decision.

A run posts in its thread with the post, artifact and decide plan operations (plans.md); decide needs the agent to be an approver of the thread.

Events#

The Events page lists them under Threads ("Eli Novak joined as observer, added by Pat Kim", "Thread closed by Erin Walsh").

CLI#

The CLI reads the state file and cannot create, post in or manage threads.

ok threads --state <path/to/state.db>              # every thread: id, owner, counts, goal
ok threads --state <path/to/state.db> --show <id>  # transcript and artifact versions
ok replay ...                                      # replay a run, thread or task from the event log

ok ask --agent <id> "<text>" asks an agent in your own conversation, not in a chosen thread.