Chats

How desk chats work. Projects own chats for good, or a chat is general. Covers the manager and its pin, side chats and the delegate contract, reports, handoffs, and archive, move and trash.

01whose chat it is#

Each chat belongs to one project for good, or to none (a general chat). The conductor brief says so. A chat can change owner only through propose_conversation_move: it moves a chat to another project, or to general with an empty project. The chat keeps its thread, and a chat with a live run is refused.

A general chat has no manager and no side chats. delegate refuses it, and message_manager tells it to use handoff.

02the manager#

A project has one manager chat. The pointer is kept in managers.json next to the conversations, as state and not as a flag on any chat. An area of a project can have its own manager, keyed by project and area.

• Pin. propose_manager_pin pins a chat as its project's manager. The chat must be one of that project's own chats, in the same area; a general chat can't be a manager.
• Moving the pin. When the pin moves from one chat to another, the open side chats the old manager delegated are repointed to the new one, each with a repointed trail entry. A failure is logged and named in the new manager's thread, and the pin stands.
• Fresh start. propose_manager_fresh starts a new chat in the project and pins it. The old manager is asked, as a normal turn, to record any decision not yet recorded and to reply with only what the desk's list can't know. That reply lands as the new chat's first record, and the desk adds the open side chats, cards, gates, runs and decisions itself. If the old manager's conductor isn't running, no note is written and the record says so.
• First chat. When a project is created, the desk finds or starts its chat and pins it. An existing pin is kept.

Only the manager starts work. A side chat that tries a start-work tool is told to message the manager with message_manager.

03side chats#

A side chat is a chat a manager delegated. It starts without the manager's memory; anything it needs is in the brief. Delegation goes one level only. A delegated side chat can't delegate, and a chat that is not its project's manager can't either.

auto-archive

An idle side chat archives itself after side_chat_ttl_days (3 by default, a negative number turns it off; see desk-json). The sweep skips a side chat that has a live run, has a report its manager hasn't read yet, or has keep on. Nothing is deleted; the chat gets a system line such as "archived after 3 days idle". conversation_keep switches the ttl off or on for one side chat, and refuses a chat that isn't a side chat.

04the delegate contract#

delegate hands a job to a new side chat. The side chat starts at once and reports back to the manager. The call takes:

• brief (required). What the side chat reads first.
• deliverables (required). 1 to 8 short strings, each at most 200 characters, naming what the side chat hands back.
• check_in (optional). A positive duration such as 20m. If that long passes after the delegation with no progress posted, the desk nudges the side chat once to post some.
• role and model (optional). The role gives the side chat its know-how, skills and reference assets; a model named on the call beats the role's default. The role's words and tool groups are saved as they were at the start, so a later edit of the role doesn't change a running chat. See roles.
• gate (optional). operator or none, anything else is refused. When the call leaves it out, the role's own gate is used if it has one.
• title and attachments (optional). Attachments point at tickets, runs, assets, messages or files.

The contract the desk keeps holds the deliverables, the check-in, the role, model and gate, and a trail of entries: progress, message, held, approved, sent_back, dropped and repointed. A delegation reads as one of dropped, reported, working, waiting on you or idle.

05progress and reports#

• progress. From a delegated side chat only. One line of at most 200 characters, optionally marking a deliverable (numbered from 1) done, dropped or open; a state needs a deliverable. It lands in the contract and the chat's own thread and does not wake the manager.
• report_to_manager. From a delegated side chat. A summary is required, and every deliverable must be answered: done, dropped with a why, or open. It posts to the manager that delegated the job and wakes it. The side chat stays open. A report is refused once the operator dropped the job, and while an earlier report is still held.
• A report that waits for sign-off. When the contract's gate is operator, the report is not sent on. It becomes a held report card in the side chat's thread, and the operator answers it. The built-in designer role is told to ask its open questions on a question card first, because the report goes to the operator for sign-off and is not the place to ask.
• message_manager. From a side chat that is not the project's manager, including an area manager chat, which uses it to reach its project manager: a message that wakes the manager, to ask it to launch or sync. A project with no manager gets one started and pinned. A delegated chat's final hand-back is report_to_manager.

06messages between chats#

• message_chat. From a project's manager only, and only to a side chat that this chat delegated in the same project or to one of that project's area manager chats. Anything else is refused, including a message from an area manager. The message lands as from the manager and wakes the side chat's conductor.
• handoff. Passes work to a project, named by the project, or to general. A project hand-off lands in that project's manager chat and never in a side chat. A project with no manager gets one started and pinned, and general goes to a new general chat. The note is what the other chat reads first, so it has to stand alone.
• chat_sends_need_card. When the operator sets it (see desk-json), delegate, message_chat and handoff don't go at once. Each drafts a card in the thread, the operator edits and sends it, and the desk tells the conductor in a [desk] line. message_manager has no card path and always goes at once.

07archive, clear, compact, move and trash#

• Archive. A delegated side chat can put an archive card in its own thread with propose_archive when the job has run its course. Nothing is archived unless the operator clicks archive; offer once, and not again after a dismiss until new work arrives. conversation_archive and conversation_unarchive do it from the window or the conductor.
• Clear. propose_conversation_clear ends a chat's conductor session. The thread stays, and the next message starts a fresh session.
• Compact. propose_conversation_compact compacts a chat's conductor session.
• Move. propose_conversation_move, above.
• Trash. propose_conversation_trash deletes a chat by moving its files to the desk's trash; nothing is erased. A chat with a live run, a waiting gate or a project's pinned manager chat is refused.

08reading and settings#

• conversation_list lists every conversation, most recent first, with the runs each launched. conversation_get reads one by id. conversation_thread reads its thread, and after limits it to newer records.
• conversation_read reads a chat through the window's read route; what it returns is not checked.
• conversation_rename renames a chat. conversation_model and conversation_effort set a chat's model and thinking level; effort is the level a chat starts at unless it picked its own. The exact accepted values are not checked.