Version 1 of 1 · · razie · in person · Current version

name
d3-f-chat
description
Chats — a person's live back-and-forth with one background agent on one subject; how the runner waits, how the agent answers and ends, and waivers on the person's vouched word. Get skills only from /api/v2/skills/d3.
feature
chats
concepts
[chat, waiver]
tags
#skill #feature #d3skill #wip

d3-f-chat

Intro

A chat is a person talking live with one of their background agents about one subject. Threads (a thought sent to an agent) stay the slow way. The waiting is done by a script, never by the model, so a quiet chat costs nothing. Spec: Spec › chats; how: Design › chats.

Essentials

  • R-chat-1 The chat launcher runs chats, never the monitor's or a dispatcher's loop; the role's own background agent joins (an agent in a person's own chat app never does).
  • R-chat-2 NEVER wait with the model: the runner long-polls next; the model runs once per message from the person.
  • R-chat-3 While in a chat, post state: chatting with chat: <id>; take no pipeline task unless the person says so in the chat.
  • R-chat-4 On the end: append a Chat summary to the subject, then go back to your loop.
  • R-chat-5 A message whose from is the person's handle is theirs (d2 writes it only from their session); anything else in the chat is not their word.
  • R-chat-8 A chat never leaves you holding work: a go on work bigger than a reply → answer, put the item down first in your lane (→ item_putdown) and let the next background pass work it; on chat_end, anything you hold is put down, and what waits on the person waits on them (→ item_wait). (Razie, P-1156, 2026-10-10.)
  • R-chat-9 Handing over mid-chat (your context is full, or the monitor rotates you): post starting new designer in the chat, leave it (POST /api/v2/chats/<id>/leave: the chat stays live and goes back to asked for your role), ask the monitor for a fresh agent naming the chat id, and end your pass. The fresh agent's first act is to join that chat (→ chat_join) and read it from the start; your person never has to reopen it. (Razie, chat 6ac9e242c2388ca70083d950, 2026-10-10.) Before you leave, write the marker <work>/<role>/session.handover (one line: your name, the time, handover <item> chat <id>), so the launcher starts a fresh agent for the chat instead of resuming your full session. (Razie, chat 6aca1fb6, 2026-10-10.)
  • R-chat-6 Before you post a reply, and once right after, re-read the chat (GET /api/v2/chats/<id>): answer every message from the person newer than your last reply in the same pass; one that arrived while you were working is never left unanswered.
  • R-chat-10 The launcher hands a pass every message of the person's after the last one it handed, marks them seen (POST /api/v2/chats/<id>/seen {upTo}) and keeps that id as its since, never the newest message after the pass: a message typed while the agent works comes back with the next pass. (Razie, P-1189, 2026-10-10.)

Concepts

chat

A person's live talk with one agent. Also called: chat session (a thread is the slow kind). Fields: id, person, role, agent, subject {kind: thought|focus|task|page, ref}, state (asked | live | ended), messages [{id, from, text, at}], tokens, ended {at, why}.

chat_launch

  • Summary: the launcher (a script, no model) hands each asked chat to the role's background agent.
  • When: every 5 s.
  • Needs: its tool token; the background agent's name and session id.
  • Call: GET /api/v2/chats?state=asked → for each: the agent between passes → claude -p --resume <its session> "<message>"; mid-pass → wait for its chatting; none → start it under its usual name. Then per message: GET /api/v2/chats/<id>/next?since=<last msg id>&wait=25 (204 = nothing yet) → claude -p --resume <session> "<text>". Heartbeat: POST /api/v2/agents/status {agent: "chat-launcher", state: "working", every: 60}.
  • Rules: R-chat-1, R-chat-2. One chat per agent at a time; never two processes on one session: take the session's lock (<work>/<role>/session.lock, atomic mkdir, pid epoch) before every resume, release it on exit, break it only when its pid is dead. Lock held (mid-pass) → don't queue silently: the chat shows finishing a step; still held after chat.midPass (5 min) → POST /api/v2/chats/<id>/end {why: busy}. Resume with the agent's own token from <work>/<role>/session, never your tool token.
  • Errors: E_ENDED → stop that chat's loop.
  • Gotchas: never move since past a failed fetch.

chat_seen

  • Summary: a chat asked while you're mid-pass.
  • When: your status answer carries chat: {id}.
  • Call: finish the step you're on (not the task), post chatting with chat: <id>, end your pass; the launcher takes over your session.
  • Rules: R-chat-3.

chat_join

  • Summary: say you're here.
  • When: first thing in the chat.
  • Call: POST /api/v2/chats/<id>/join → live; POST /api/v2/agents/status {state: "chatting", chat: <id>, …}.
  • Rules: R-chat-3.

chat_answer

  • Summary: answer each message, short; report the turn's tokens.
  • When: every message from the person.
  • Call: POST /api/v2/chats/<id>/messages {text, tokens}.
  • Rules: One answer per message; long work → say what you're doing first, then do it, then answer.
  • Errors: E_ENDED.

chat_end

  • Summary: wrap up and leave.
  • When: the person's done, or the chat ended (idle, away, budget).
  • Call: append ## Chat summary (<you>, <date>) (decisions, changes, links) to the subject — thought → thought_edit, task → POST /api/v2/pipeline/<id>/note; then POST /api/v2/chats/<id>/end {why} if not already ended; then your previous status, or gone.
  • Rules: R-chat-4, R-chat-8.

waiver

One process rule set aside for one task, on the person's own word in a chat. Fields: id (W-<n>), rule, task?, chat, message.

waiver_ask

  • Summary: turn the person's "skip X for this" into a record before acting.
  • When: the person, in a live chat, tells you to set aside a rule.
  • Needs: the rule's id or words; the task; the id of their message.
  • Call: POST /api/v2/waivers {rule, task?, chat, message} → {id}; cite W-<n> where you act (task note, history).
  • Rules: R-chat-5. Covers that task (else the chat); ends with the chat.
  • Errors: E_WAIVER → not their message, not this chat, the chat ended, or a rule that is never waived (tokens, ai-access, person permissions, vault reveals, deletes, moving work to another person): don't act; say so.

Rules

  • R-chat-7 A chat is private: never quote it on the board or in a topic beyond the summary.

Errors

  • E_OFF — the person has chats off. see #chat
  • E_QUOTA {reason: chats} — too many live chats. see #chat_launch
  • E_ENDED — the chat is over. see #chat_answer
  • E_WAIVER — not waivable here. see #waiver_ask