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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/** A person's decisions (design: decisions in one place). The Lead, or a worker on its own task through needs_human, asks
* one person a batch of questions, each with options, a recommendation and what it unblocks; the person answers each
* with one tap, and the answer reaches the asking agent and the Lead in the conversation it came from. Decisions live in
* SuperTabDecision, never in the tab state, as mentions do. A decision is not a private channel: the PM's private lines go
* to the person's Buddy chat (buddies.ts). Called inside SuperTabStore's transactions. */
import { defaultBuddyChat, isBuddy, isBuddyChat, isSwarmBuddy, openBuddyChat, ownAgentAuthor, PROPOSAL_ASK_MS, sessionProjectId } from './buddies.js'
import { switched } from './boardRights.js'
import { usernameOf } from './usernames.js'
import { agentWrittenNameOf } from './personNames.js'
import { createHash } from 'node:crypto'
import type { Prisma } from '@prisma/client'
import { z } from 'zod'
import { AGENT_ONLY, fail, isLeads, person, stableId, type Actor, type Agent, type Author, type Conversation, type MessageDraft, type SuperTabState } from './model.js'
import { agentProjectId, canReadGroup, groupProject, isClosedPmChat, ledProject, projectAgent, projectsOf, readsRecordsIn } from './projects.js'
import { LEDGER_WEEKS } from './leaderboard/record.js'
import { coordinatorNameOf } from './instructions.js'
import { WEEK_MS } from './leaderboard/week.js'
import { groupsBy } from './parts/indexed.js'
type Tx = Prisma.TransactionClient
export const MAX_QUESTIONS = 10
/** Open decisions one asker may hold for one person: an asker whose question changes a little every turn would otherwise
* write without end, and push real decisions out of the person's list. */
export const MAX_OPEN_DECISIONS = 20
const line = (max: number) => z.string().trim().min(1).max(max)
/** What a question offers besides itself: 2–5 distinct options, the index of the recommended one, and what an answer unblocks. */
export const decisionChoices = z.object({ options: z.array(line(200)).min(2).max(5).refine(o => new Set(o).size === o.length, 'Give distinct options.'),
recommended: z.number().int().min(0), unblocks: line(300),
defaultAt: z.string().datetime({ offset: true }).transform(value => new Date(value).toISOString()).optional(),
/** A rule says the person must agree (task #3826): at defaultAt the PM is told instead of the default applying. */
mustAgree: z.literal(true).optional() }).strict()
export const decisionQuestion = decisionChoices.extend({ question: line(1000) }).strict()
type Question = z.infer<typeof decisionQuestion>
/** Give a person time to see the question before its recommendation can apply automatically. */
export const MIN_DEFAULT_DELAY_MS = 15 * 60_000
export function checkDecisionDeadline(question: { defaultAt?: string }, now: number): void {
if (question.defaultAt && Date.parse(question.defaultAt) < now + MIN_DEFAULT_DELAY_MS) {
fail('INVALID_DECISION', 'Set the default time at least 15 minutes ahead so the person can answer.', 400)
}
}
/** The kind of a decision the nightly routing reflection asks (costs/reflection.ts): about the project's routing, so its
* owner's Buddy never reads it, and an approved one stays until routing applies it (review of #2276). */
export const REFLECTION_DECISION = 'routing-reflection'
/** Not a routing reflection's: rows written before `kind` have none. */
const notReflection: Prisma.SuperTabDecisionWhereInput = { OR: [{ kind: { isSet: false } }, { kind: null }, { kind: { not: REFLECTION_DECISION } }] }
/** A person's own Buddy's question to them (task #4525, anh Dee 11-07: everything waiting on a person shows in their Decisions).
* Never the PM's to take: no Let PM decide and no 24-hour sweep, only its own default time when it set one. */
export const BUDDY_DECISION = 'buddy'
/** A Buddy's line waiting for its owner's OK to post to a project's PM: Send posts the stored words (`send`), Not now posts
* nothing. No default time: only its owner sends. */
export const BUDDY_SEND = 'buddy-send'
export const SEND_OPTIONS = ['Send', 'Not now']
export const isBuddyDecision = (kind: string | null | undefined): boolean => kind === BUDDY_DECISION || kind === BUDDY_SEND
/** A PM's question on a proposal card (proposal.ask) as its person's Decision (task #4547): its default answer is the option, a
* typed answer any other; answering it answers the card, and an answer on the card closes it. */
export const PROPOSAL_QUESTION = 'proposal-question'
type DecisionKind = typeof REFLECTION_DECISION | typeof BUDDY_DECISION | typeof BUDDY_SEND | typeof PROPOSAL_QUESTION
/** The Decision a proposal card's question is, by the question's id, so the card finds it again. */
export const proposalQuestionDecisionId = (questionId: string): string => stableId(questionId, 'decision')
/** [q] on [card] as a Decision for the person asked: its deadline the default time, or with required agreement the time the PM
* is told (mustAgree). The card's own clock answers it too; whichever comes first counts. */
export function proposalQuestionDecision(state: SuperTabState, card: Conversation, q: { id: string; personId: string; question: string; defaultAnswer: string;
deadline: number; requiresConsent: boolean }, askerAgentId: string, operationId: string): DecisionDraft {
return { id: proposalQuestionDecisionId(q.id), batchId: operationId, conversationId: card.id, projectId: groupProject(state, card).id, personId: q.personId,
askerAgentId, assignmentId: null, question: `${card.title}: ${q.question}`, options: [q.defaultAnswer], recommended: 0, unblocks: 'The PM\'s decision on this proposal',
defaultAt: new Date(q.deadline).toISOString(), ...q.requiresConsent ? { mustAgree: true as const } : {}, kind: PROPOSAL_QUESTION }
}
/** Closes decisions whose question was answered elsewhere: answered, with no choice, as a withdrawn one is (withdrawIn). One by
* one by id: a command closes one. */
export async function closeDecisions(tx: Tx, tabId: string, ids: readonly string[], now: number): Promise<void> {
for (const id of new Set(ids)) await tx.superTabDecision.updateMany({ where: { id, tabId, ...waiting }, data: { answeredAt: new Date(now), withdrawn: true } })
}
/** What Send posts, as buddy.propose takes it: the words shown, and what goes to the PM with them. */
export interface SendPayload { text: string; projectId: string; goal: string; scope: string; priority: string; title?: string; why?: string; doneWhen?: string; evidence?: string[] }
/** A question as an asker gives it, with what only a Buddy's carries: its project, its kind and, for a send line, the words. */
export type AskedQuestion = Question & { projectId?: string; kind?: DecisionKind; send?: SendPayload }
/** A decision as asked, written by the store. */
export interface DecisionDraft extends Question {
id: string; batchId: string; conversationId: string; projectId: string; personId: string; askerAgentId: string; assignmentId: string | null
kind?: DecisionKind; send?: SendPayload
}
/** The decision `decision.answer` names, read from SuperTabDecision by the store. */
export interface DecisionTarget {
id: string; personId: string; conversationId: string; projectId: string; askerAgentId: string; question: string; options: string[]
/** The option Let PM decide takes; a row whose index is not one of its options has none. */
recommended: number; answeredAt: number | null
defaultAt?: number | null
/** When it was asked, and the task whose needs_human asked it: the leaderboard credits the answer (leaderboard/record.ts). */
createdAt: number; assignmentId: string | null
kind?: string | null
/** Closed unanswered once its work was over (withdrawIn). */
withdrawn?: boolean
mustAgree?: boolean
/** A Buddy's send line: the words its Send posts (BUDDY_SEND). */
send?: SendPayload | null
}
/** `delegated`: the person asked left it to the PM, who took the recommended option. */
/** `choice` null with a `note`: the person typed their own answer instead of choosing an option (task #2996). */
export interface DecisionAnswer { id: string; choice: number | null; note: string | null; delegated?: true
/** Left to the PM by the hourly sweep after 24 hours unanswered, not by the person (overdueDecisions.ts). */
overdue?: true; defaulted?: true }
/** Questions for one person in one conversation they read, from `asker`. One batch: one id ties them, no ping per question. */
export function askDecisions(state: SuperTabState, group: Conversation, personId: string, questions: AskedQuestion[],
from: { now: number; operationId: string; askerAgentId: string; assignmentId: string | null; kind?: typeof REFLECTION_DECISION }): DecisionDraft[] {
const asked = state.people.find(p => p.id === personId) ?? fail('INVALID_PERSON', 'Ask a person in this Swarm.', 400)
if (!canReadGroup(state, { kind: 'person', userId: asked.id, email: asked.email }, group)) {
fail('INVALID_PERSON', `${usernameOf(state, asked.id)} cannot read this conversation.`, 400)
}
for (const q of questions) checkDecisionDeadline(q, from.now)
for (const q of questions) if (q.recommended >= q.options.length) fail('INVALID_DECISION', 'A question must recommend one of its options.', 400)
// It would wait for nobody: none waits where the work is over (workOver).
if (workOver(state, group)) fail('WORK_FINISHED', 'This work is finished, so a decision asked here would not wait. Ask in the project chat, or reopen the task first.', 400)
return questions.map((q, index) => ({ ...q, id: stableId(from.operationId, 'decision', String(index)), batchId: from.operationId,
conversationId: group.id, projectId: q.projectId ?? groupProject(state, group).id, personId, askerAgentId: from.askerAgentId,
assignmentId: from.assignmentId, ...from.kind ? { kind: from.kind } : {} }))
}
/** A Buddy asks only its own owner, at their current membership, in its own chat (task #4525): the server holds it to that,
* whatever it names. The project its questions are about: a session's own, a project chat's, or the one it names that its
* owner reads (checked by the caller, readProject); a Swarm-wide Buddy may name none, '' then. */
export function checkBuddyAsker(state: SuperTabState, buddy: Agent, group: Conversation, personId: string, named: string | undefined): string {
const owner = state.people.find(p => p.id === buddy.buddyOf!.personId && p.generation === buddy.buddyOf!.generation)
if (!owner || personId !== owner.id) fail('BUDDY_ASKS_OWNER', 'A Buddy asks only its own owner.', 403)
if (!isBuddyChat(group) || !group.agentIds.includes(buddy.id)) fail('BUDDY_FORBIDDEN', 'A Buddy asks only in its own chat.', 403)
const own = sessionProjectId(buddy) ?? (group.kind === 'buddy' ? groupProject(state, group).id : undefined)
if (own && named && named !== own) fail('NOT_FOUND', 'This project is unavailable.', 404)
return own ?? named ?? ''
}
/** Whether an agent's ask in [group] goes to the person directly, never through the PM: in a switched project (boardRights.ts;
* task #3826, spec "When an agent needs a person"). Elsewhere people talk only to the PM (crewNeeds.ts). */
export const asksDirectly = (state: SuperTabState, group: Conversation): boolean => switched(groupProject(state, group))
/** A direct ask always says when its recommendation applies: the person may be away, and the work must not wait without end. */
export function checkDirectAsk(questions: ReadonlyArray<{ defaultAt?: string }>): void {
if (questions.some(q => !q.defaultAt)) {
fail('INVALID_DECISION', 'In this project you ask the person directly, so each question needs defaultAt: the time its recommended option applies if they have not answered (at least 15 minutes ahead).', 400)
}
}
/** Each asked decision's line in its person's default Buddy chat, to their default Buddy, which brings it to them: the Buddy
* cannot answer it (answerable), the person answers in their Needs you list. Marked with its project, so it hides once they
* lose it (buddies.ts hiddenProjectRow). Written by that Buddy, naming [asker], the agent that asked: only the person and their
* own agent post in their private chat (task #4558). With no Buddy there is no line; the ask waits in Needs you. */
export function askedThroughBuddy(state: SuperTabState, group: Conversation, drafts: readonly DecisionDraft[], asker: Author): MessageDraft[] {
return drafts.flatMap(d => {
const to = person(state, d.personId)
const author = ownAgentAuthor(state, to)
if (!author) return []
const options = d.options.map((o, i) => i === d.recommended ? `${o} (recommended)` : o).join(' / ')
const task = group.number ? ` on task #${group.number}` : ''
const text = `${asker.displayName ?? asker.name} asks ${usernameOf(state, to.id)}${task}: ${d.question}\n\nOptions: ${options}\n`
+ `Unblocks: ${d.unblocks}\n` + (d.mustAgree
? `No default applies: your agreement is required. At ${d.defaultAt}, the PM is told if you have not answered.`
: `At ${d.defaultAt}, if not answered: ${d.options[d.recommended]!}.`)
return [{ id: stableId(d.id, 'buddy'), conversationId: defaultBuddyChat(state, to).id, author, text, replyTo: null,
recipients: [author.id], source: { kind: DECISION_ASKED_KIND, decisionId: d.id, projectId: d.projectId }, buddyProject: d.projectId }]
})
}
export const DECISION_ASKED_KIND = 'decision-asked'
/** Any agent of the project asks with `decision.ask`, in its own project's conversations (project instructions, phase 4); a
* worker may also ask through needs_human. */
export function checkAsker(state: SuperTabState, actor: Actor, group: Conversation): string {
// A person's Buddy chat is theirs and their Buddy's: no other agent asks there (task #4525).
if (isLeads(group) || isBuddyChat(group) || !projectAgent(state, actor, groupProject(state, group).id)) {
fail('FORBIDDEN', 'An agent asks for decisions in its own project’s conversations.', 403)
}
return actor.agentId
}
/** Whether the work a decision was asked about is over, so it waits no more (Dee, 10-31: decisions of tasks already done and
* merged still said they waited): a work group whose task is done or cancelled, or which is archived. Never a project chat,
* a Buddy chat or a closed Chat with PM, which hold no task of their own (tidy.ts archivable leaves them out alike). A
* deleted group is none: the reads find no conversation for its decisions. Reads only what an access check of a quiet
* conversation brings (ACCESS_FIELDS). */
export function workOver(state: SuperTabState, group: Pick<Conversation, 'id' | 'kind' | 'audience' | 'archived' | 'assignment'>): boolean {
if (group.kind || group.audience || projectsOf(state).some(p => p.leadConversationId === group.id)) return false
return group.archived === true || ['done', 'cancelled'].includes(group.assignment?.status ?? '')
}
/** The answer a decision whose work is over gets: the code an answered one gets, which a client already takes as gone. */
const NO_LONGER_WAITS = 'This decision no longer waits: its work is finished.'
/** The conversation a decision was asked in, while the person asked is still in the Swarm and still reads it, or read it
* before it closed as a Chat with PM: checked on every answer and on every retry of one (review of #1753). Anyone else is
* told it does not exist. */
export function answerable(state: SuperTabState, actor: Actor, decision: DecisionTarget | undefined): Conversation {
const asked = actor.kind === 'person' && decision?.personId === actor.userId && state.people.some(p => p.id === actor.userId)
const group = asked ? state.conversations.find(c => c.id === decision.conversationId) : undefined
if (!group || !readsRecordsIn(state, actor, group)) fail('NOT_FOUND', 'This decision is unavailable.', 404)
return group
}
/** The conversation of a decision [actor] may answer: the person asked (answerable), or for a Buddy's own question to its owner,
* that Buddy while still theirs and in its chat (task #4525). Checked on every answer and every retry of one. */
export function answerableBy(state: SuperTabState, actor: Actor, decision: DecisionTarget | undefined): Conversation {
if (actor.kind === 'person') return answerable(state, actor, decision)
const buddy = state.agents.find(a => a.id === actor.agentId && isBuddy(a))
const owner = buddy && state.people.find(p => p.id === buddy.buddyOf!.personId && p.generation === buddy.buddyOf!.generation)
const chat = decision && state.conversations.find(c => c.id === decision.conversationId)
if (!buddy || !owner || !decision || !chat || !isBuddyDecision(decision.kind) || decision.askerAgentId !== buddy.id || decision.personId !== owner.id
|| !chat.agentIds.includes(buddy.id)) fail('NOT_FOUND', 'This decision is unavailable.', 404)
return chat
}
/** What tells the asking agent and the Lead, whichever of them is still in the conversation. A notice only they read, with
* none of the answer in it: the decisions read, which checks who reads it, has the answer (review of #1753). */
export const ANSWERED_NOTICE = 'A decision asked in this conversation was answered. Read the answer with: harness super-tab decisions --answered'
/** The same notice for a decision the person left to the PM, with none of the answer either; [name] is what its project calls
* its coordinator (instructions.ts coordinatorNameOf). */
export const delegatedNotice = (name: string) => `A decision asked in this conversation was left to the ${name}, who took its recommended option. `
+ 'Read it with: harness super-tab decisions --answered'
/** The notice for a decision left to the PM by the sweep, not the person: it says why, so nobody reads it as their choice. */
export const defaultedNotice = 'A decision you asked reached its default time. The server applied its recommended option. Read it with: harness super-tab decisions --answered'
export const overdueNotice = (name: string) => `A decision asked in this conversation waited 24 hours, so it was left to the ${name}, who took its recommended option. `
+ 'Read it with: harness super-tab decisions --answered'
/** The notices for a decision asked in a closed Chat with PM, told in the project chat instead: never "in this conversation". */
export const CLOSED_CHAT_ANSWERED_NOTICE = 'A decision you asked in a closed Chat with PM was answered. Read the answer with: harness super-tab decisions --answered'
export const closedChatDelegatedNotice = (name: string) => `A decision you asked in a closed Chat with PM was left to the ${name}, who took its recommended option. `
+ 'Read it with: harness super-tab decisions --answered'
/** How an answer reads in the decisions list: a delegated one never as the person's own choice. */
const answerText = (option: string, delegated: boolean) => delegated ? `PM decided: ${option}` : option
/** The asked person's one answer (an option, their own words as `note` alone, or both), or their leaving it to the PM
* (`delegate`), which takes the recommended option; the notice
* for the asking agent and the Lead, in the conversation it was asked in or, for a closed Chat with PM nobody reads, in
* the project chat (`noticeIn`); and for a delegated one, the Lead's line in the person's Buddy chat. */
export function answerDecision(state: SuperTabState, actor: Actor, decision: DecisionTarget | undefined,
given: { choice?: number; note: string | null; delegate: boolean; overdue?: boolean; defaulted?: boolean; now?: number }) {
if (given.choice !== undefined ? given.delegate : !given.delegate && given.note === null) {
fail('INVALID_DECISION', 'Choose one of its options, type an answer, or leave it to the PM.', 400)
}
if (given.overdue && !given.delegate) fail('INVALID_DECISION', 'Only a decision left to the PM can be overdue.', 400)
const group = answerable(state, actor, decision)
const asked = decision!
if (asked.withdrawn || workOver(state, group)) fail('DECISION_ANSWERED', NO_LONGER_WAITS)
if (asked.answeredAt !== null) fail('DECISION_ANSWERED', 'This decision is already answered.')
if (given.delegate && !(asked.recommended >= 0 && asked.recommended < asked.options.length)) {
fail('INVALID_DECISION', 'This decision has no recommended option to leave to the PM.', 400)
}
if (given.defaulted && (!given.delegate || asked.kind === REFLECTION_DECISION || asked.defaultAt == null || given.now == null || asked.defaultAt > given.now)) {
fail('INVALID_DECISION', 'This decision has not reached its default time.', 400)
}
if (given.overdue && asked.defaultAt != null) fail('INVALID_DECISION', 'This decision uses its explicit default time.', 400)
const choice = given.delegate ? asked.recommended : given.choice ?? null
if (choice !== null && choice >= asked.options.length) fail('INVALID_DECISION', 'Choose one of its options.', 400)
const project = groupProject(state, group)
const lead = state.conversations.find(c => c.id === project.leadConversationId)?.leadId
const closed = isClosedPmChat(group)
const noticeIn = closed ? state.conversations.find(c => c.id === project.leadConversationId)! : group
const delegatedText = closed ? closedChatDelegatedNotice : given.overdue ? overdueNotice : delegatedNotice
const notice = given.defaulted ? defaultedNotice : given.delegate ? delegatedText(coordinatorNameOf(project))
: closed ? CLOSED_CHAT_ANSWERED_NOTICE : ANSWERED_NOTICE
const recipients = [...new Set([asked.askerAgentId, ...lead ? [lead] : []])].filter(id => noticeIn.agentIds.includes(id))
const answer: DecisionAnswer = { id: asked.id, choice, note: given.note, ...given.delegate ? { delegated: true as const, ...given.overdue ? { overdue: true as const } : {}, ...given.defaulted ? { defaulted: true as const } : {} } : {} }
// A routing reflection's never reaches the Buddy chat: the person's Buddy reads it (review of #2276).
const line = given.delegate && lead && asked.kind !== REFLECTION_DECISION ? delegatedLine(state, project.id, lead, asked, asked.recommended, given.defaulted) : null
return { answer, noticeIn: noticeIn.id, notice, recipients, source: { ...AGENT_ONLY, decisionId: asked.id }, line }
}
/** The owner's message in their Buddy's chat that the Buddy names as their answer to its question, as the store reads it:
* `newest` says it is their newest message there. */
export interface OwnerAnswer { id: string; conversationId: string; author: Author; source: boolean; createdAt: number; newest: boolean }
/** The line in a Buddy chat that settles its decision there: its owner answered in Decisions, or a Send went. */
export const DECISION_ANSWERED_KIND = 'decision-answered'
/** An answer to a person's own Buddy's question (task #4525): theirs, in Decisions or its card in the chat; or the Buddy's, settling it
* from their answer in its chat, which it names (`ownerMessageId`): their own message there, after the question. Never the PM's:
* only its own default time applies, by the sweep. A Send posts its stored words (`send`), and from the Buddy only while the owner's
* ok is their newest message or under an hour old, as buddy.propose. The line tells the Buddy of its owner's answer in Decisions,
* and the owner of every Send, in the chat. */
export function settleBuddyDecision(state: SuperTabState, actor: Actor, decision: DecisionTarget | undefined,
given: { choice?: number; note: string | null; delegate: boolean; defaulted?: boolean; now: number; ownerMessageId?: string; ownerAnswer?: OwnerAnswer }) {
if (given.choice !== undefined ? given.delegate : !given.delegate && given.note === null) fail('INVALID_DECISION', 'Choose one of its options, or type an answer.', 400)
const group = answerableBy(state, actor, decision)
const asked = decision!
if (actor.kind === 'agent') {
const said = given.ownerAnswer, owner = person(state, asked.personId)
if (!said || said.id !== given.ownerMessageId || said.conversationId !== group.id || said.source || said.author.kind !== 'person'
|| said.author.id !== owner.id || said.author.membershipGeneration !== owner.generation || said.createdAt < asked.createdAt) {
fail('BUDDY_DECISION_UNASKED', 'Settle a decision only with your owner\'s answer: name their message in your chat that answered it.', 403)
}
}
if (asked.answeredAt !== null || asked.withdrawn) fail('DECISION_ANSWERED', 'This decision is already answered.')
const due = given.defaulted === true && actor.kind === 'person' && asked.kind !== BUDDY_SEND && asked.defaultAt != null && asked.defaultAt <= given.now
if (given.delegate && !due) fail('INVALID_DECISION', 'Choose one of its options, or type an answer.', 400)
const choice = given.delegate ? asked.recommended : given.choice ?? null
if (choice !== null && (choice < 0 || choice >= asked.options.length)) fail('INVALID_DECISION', 'Choose one of its options.', 400)
const sends = asked.kind === BUDDY_SEND && choice === 0
const said = given.ownerAnswer
if (sends && actor.kind === 'agent' && !said!.newest && given.now - said!.createdAt > PROPOSAL_ASK_MS) {
fail('PROPOSAL_STALE', 'Send for your owner\'s newest message in your chat, or one from the last hour. Ask them again.', 403)
}
const answer: DecisionAnswer = { id: asked.id, choice, note: given.note, ...given.delegate ? { delegated: true as const, defaulted: true as const } : {} }
const words = sends ? 'Sent' : given.delegate ? `Default applied: ${asked.options[choice!]!}` : choice !== null ? asked.options[choice]! : given.note!
const tell = actor.kind === 'person' && group.agentIds.includes(asked.askerAgentId) ? [asked.askerAgentId] : []
const line = actor.kind === 'person' || sends ? { conversationId: group.id, text: `${words} — ${asked.question.replace(/\s+/g, ' ')}`, recipients: tell,
source: { kind: DECISION_ANSWERED_KIND, decisionId: asked.id } } : null
return { answer, line, send: sends ? asked.send ?? fail('INVALID_DECISION', 'This decision has nothing to send.', 400) : null, buddyId: asked.askerAgentId }
}
export const MUST_AGREE_KIND = 'decision-must-agree'
/** What the PM is told when a decision its person must agree to reaches its time unanswered: none of the question, which the
* PM reads in its decisions; the sweep never applies the default (task #3826, spec "When an agent needs a person"). */
export function mustAgreePassed(state: SuperTabState, actor: Actor, decision: DecisionTarget | undefined, now: number) {
const group = answerable(state, actor, decision)
const asked = decision!
if (asked.withdrawn || workOver(state, group)) fail('DECISION_ANSWERED', NO_LONGER_WAITS)
if (asked.answeredAt !== null) fail('DECISION_ANSWERED', 'This decision is already answered.')
if (!asked.mustAgree || asked.defaultAt == null || asked.defaultAt > now) fail('INVALID_DECISION', 'This decision has not reached its default time.', 400)
const project = groupProject(state, group)
const lead = state.conversations.find(c => c.id === project.leadConversationId)?.leadId
const noticeIn = isClosedPmChat(group) ? state.conversations.find(c => c.id === project.leadConversationId)! : group
const text = `A decision ${usernameOf(state, asked.personId)} must agree to reached its default time unanswered, so no default applied: `
+ 'it waits for them. Read it with: harness super-tab decisions'
return { noticeIn: noticeIn.id, text, recipients: lead && noticeIn.agentIds.includes(lead) ? [lead] : [], source: { kind: MUST_AGREE_KIND, decisionId: asked.id } }
}
/** The one line saying what the Lead chose, in the person's own Buddy chat of that project: only they and their Buddy read
* it, and they were asked the question. Opened for the line when they have none (buddies.ts openBuddyChat). */
function delegatedLine(state: SuperTabState, projectId: string, leadId: string, asked: DecisionTarget, choice: number, defaulted = false) {
const to = person(state, asked.personId)
// Written by their own agent, as only they and it post in their private chat (task #4558); with none, Needs you shows it.
const author = state.agents.some(a => a.id === leadId) ? ownAgentAuthor(state, to) : undefined
if (!author) return null
const question = asked.question.replace(/\s+/g, ' ')
const text = `${defaulted ? `Default applied: ${asked.options[choice]!}` : answerText(asked.options[choice]!, true)} — ${question}`
// In their one Buddy chat, marked with its project (Dee, 10-31), and in their older chat there for older apps.
return [{ conversationId: defaultBuddyChat(state, to).id, author, text, source: { kind: 'decision-delegated', decisionId: asked.id, projectId }, buddyProject: projectId },
{ conversationId: openBuddyChat(state, projectId, to).id, author, text, source: { kind: 'decision-delegated', decisionId: asked.id } }]
}
/** Mongo omits unset fields, so `answeredAt: null` alone would miss a row written without it. */
const waiting: Prisma.SuperTabDecisionWhereInput = { OR: [{ answeredAt: null }, { answeredAt: { isSet: false } }] }
/** How many decisions asked of `personId` in this conversation still wait for them (catchUp.ts). */
export async function waitingFor(tx: Tx, tabId: string, conversationId: string, personId: string): Promise<number> {
return tx.superTabDecision.count({ where: { tabId, conversationId, personId, ...waiting } })
}
/** Closes the decisions still waiting in these conversations, whose work is over (workOver), as withdrawn: answered at
* [now] with no choice, so none waits, none is listed, none can be answered and a new ask of the same question is a new
* decision. Never a routing reflection's, which expires on its own (expireReflections). Run in the transaction that ends
* the work (store.ts), so a concurrent answer conflicts with it and only one of them counts. With [askedBy], only those
* asked by then: the work was read as over at that time (store.ts withdrawEndedDecisions). The number closed. */
export async function withdrawIn(tx: Tx, tabId: string, conversationIds: readonly string[], now: number, askedBy?: number): Promise<number> {
let closed = 0
// One by one through the conversation index: a command ends one conversation's work, rarely a few (hotFilters.test.ts).
for (const conversationId of new Set(conversationIds)) {
closed += (await tx.superTabDecision.updateMany({ where: { tabId, conversationId, AND: [waiting, notReflection],
...askedBy === undefined ? {} : { createdAt: { lte: new Date(askedBy) } } },
data: { answeredAt: new Date(now), withdrawn: true } })).count
}
return closed
}
/** The conversations, by Swarm, where a decision still waits, a routing reflection's aside (store.ts withdrawEndedDecisions,
* once at worker startup). Open decisions are few: at most MAX_OPEN_DECISIONS per asker and person. */
export async function waitingConversations(tx: Tx): Promise<Map<string, string[]>> {
const rows = await tx.superTabDecision.findMany({ where: { AND: [waiting, notReflection] }, select: { tabId: true, conversationId: true },
distinct: ['tabId', 'conversationId'] })
const byTab = new Map<string, string[]>()
for (const row of rows) byTab.set(row.tabId, [...byTab.get(row.tabId) ?? [], row.conversationId])
return byTab
}
/** The conversations whose work this write ended (workOver in [after], not in [before]): their waiting decisions close. */
export function workEnded(before: SuperTabState, after: SuperTabState): string[] {
const was = new Map(before.conversations.map(c => [c.id, c]))
return after.conversations.filter(c => workOver(after, c) && !(was.has(c.id) && workOver(before, was.get(c.id)!))).map(c => c.id)
}
/** What makes an ask a repeat: the same asker, task, person, conversation, question, options, recommendation, agreement requirement
* and what it unblocks. Another asker, another task or other options with the same text is a decision of its own (review of #1753). */
const repeatKey = (d: Pick<DecisionDraft, 'askerAgentId' | 'assignmentId' | 'personId' | 'conversationId' | 'question' | 'options' | 'recommended' | 'unblocks'> & { defaultAt?: string | Date | null; mustAgree?: boolean | null }) =>
JSON.stringify([d.askerAgentId, d.assignmentId ?? null, d.personId, d.conversationId, d.question, d.options, d.recommended, d.unblocks, d.defaultAt ? new Date(d.defaultAt).toISOString() : null, d.mustAgree === true])
/** Writes the questions asked and returns the decision each one is: an open decision that this ask exactly repeats is that
* decision again, not a second one. New ones beyond MAX_OPEN_DECISIONS from this asker to this person are refused, and
* writing them removes the tab's decisions answered before the leaderboard's weeks. Read and written in the command's
* transaction; asks committing at the same moment each pass the check, so together they can still be written twice or
* go past the cap by what they add. */
export async function writeDecisions(tx: Tx, tabId: string, drafts: DecisionDraft[], now: number): Promise<string[]> {
if (!drafts.length) return []
const { personId, askerAgentId } = drafts[0]!
const open = await tx.superTabDecision.findMany({ where: { tabId, personId, conversationId: drafts[0]!.conversationId,
askerAgentId, question: { in: drafts.map(d => d.question) }, ...waiting } })
const held = new Map(open.map(o => [repeatKey(o), o.id]))
const fresh = drafts.filter(d => !held.has(repeatKey(d)))
if (fresh.length) {
const asked = await tx.superTabDecision.count({ where: { tabId, personId, askerAgentId, ...waiting } })
if (asked + fresh.length > MAX_OPEN_DECISIONS) {
fail('DECISIONS_FULL', `${asked} decisions you asked this person are still open, and at most ${MAX_OPEN_DECISIONS} can be. Wait for answers before asking more.`)
}
await tx.superTabDecision.createMany({ data: fresh.map(d => ({ ...d, defaultAt: d.defaultAt ? new Date(d.defaultAt) : undefined, send: d.send ? { ...d.send } : undefined,
tabId, createdAt: new Date(now) })) })
await tx.superTabDecision.deleteMany({ where: { tabId, answeredAt: { lt: new Date(now - LEDGER_WEEKS * WEEK_MS) } } })
}
return drafts.map(d => held.get(repeatKey(d)) ?? d.id)
}
/** The open decision an ask exactly repeats, which writeDecisions keeps as that decision again. Read before a worker's
* needs_human that asks, so its wait names the decision it is waiting on (leaderboard/record.ts recordStatus). */
export async function repeatOf(tx: Tx, tabId: string, ask: Parameters<typeof repeatKey>[0]): Promise<string | undefined> {
const same = await tx.superTabDecision.findMany({ where: { tabId, personId: ask.personId, askerAgentId: ask.askerAgentId,
conversationId: ask.conversationId, question: ask.question, ...waiting } })
return same.find(o => repeatKey(o) === repeatKey(ask))?.id
}
/** How many decisions this asker has open for this person when one more question would pass MAX_OPEN_DECISIONS, or null when
* it fits. Read before a worker's needs_human asks something new (an exact repeat of an open one, repeatOf, always fits),
* which at the cap still records its status and only skips the question (review of #1859). */
export async function fullFor(tx: Tx, tabId: string, ask: { personId: string; askerAgentId: string }): Promise<number | null> {
const asked = await tx.superTabDecision.count({ where: { tabId, personId: ask.personId, askerAgentId: ask.askerAgentId, ...waiting } })
return asked < MAX_OPEN_DECISIONS ? null : asked
}
/** A project's routing reflection decisions, newest first, through the project index: at most MAX_PROPOSALS are asked a
* night, and answered ones go after the ledger's weeks (store.ts postReflection). */
export async function reflectionDecisions(tx: Tx, tabId: string, projectId: string) {
return tx.superTabDecision.findMany({ where: { tabId, projectId, kind: REFLECTION_DECISION },
select: { id: true, question: true, unblocks: true, choice: true, answeredAt: true, createdAt: true, delegated: true }, orderBy: { createdAt: 'desc' }, take: 500 })
}
/** Days a routing reflection's proposal stays open unanswered: its week's numbers are stale by then (review of #2276). */
export const REFLECTION_OPEN_DAYS = 7
/** Removes a project's routing proposals left unanswered for REFLECTION_OPEN_DAYS, through the project index. Run on every
* night the project's report is due, a report or not (delta review of #2276). */
export async function expireReflections(tx: Tx, tabId: string, projectId: string, now: number): Promise<void> {
await tx.superTabDecision.deleteMany({ where: { tabId, projectId, kind: REFLECTION_DECISION,
createdAt: { lt: new Date(now - REFLECTION_OPEN_DAYS * 24 * 3_600_000) }, ...waiting } })
}
export async function readAskedDecision(tx: Tx, tabId: string, id: string): Promise<DecisionTarget | undefined> {
const row = await tx.superTabDecision.findFirst({ where: { id, tabId },
select: { id: true, personId: true, conversationId: true, projectId: true, askerAgentId: true, question: true, options: true, recommended: true,
answeredAt: true, defaultAt: true, createdAt: true, assignmentId: true, kind: true, withdrawn: true, mustAgree: true, send: true } })
return row ? { ...row, answeredAt: row.answeredAt?.getTime() ?? null, defaultAt: row.defaultAt?.getTime() ?? null, createdAt: row.createdAt.getTime(), assignmentId: row.assignmentId ?? null,
withdrawn: row.withdrawn === true, mustAgree: row.mustAgree === true, send: (row.send ?? null) as SendPayload | null } : undefined
}
/** A must-agree decision past its time keeps waiting for its person: its time is cleared, so the due range never reads it again
* and the PM is told once. Conflicts with a concurrent answer, as recordAnswer does. */
export async function keepWaiting(tx: Tx, tabId: string, id: string): Promise<void> {
const kept = await tx.superTabDecision.updateMany({ where: { id, tabId, mustAgree: true, defaultAt: { not: null }, ...waiting }, data: { defaultAt: null } })
if (!kept.count) fail('DECISION_ANSWERED', 'This decision is already answered.')
}
/** Conflicts with a concurrent answer of the same decision: only the first one counts. */
export async function recordAnswer(tx: Tx, tabId: string, answer: DecisionAnswer, now: number): Promise<void> {
const taken = await tx.superTabDecision.updateMany({ where: { id: answer.id, tabId, ...waiting },
data: { choice: answer.choice, note: answer.note, answeredAt: new Date(now), ...answer.delegated ? { delegated: true } : {},
...answer.overdue ? { overdue: true } : {}, ...answer.defaulted ? { defaulted: true } : {} } })
if (!taken.count) fail('DECISION_ANSWERED', 'This decision is already answered.')
}
/** Whose decisions a reader sees: a person, those asked of them in conversations they still read; an agent, those it asked,
* and a Lead also those asked in its project. Nobody else, owners included. */
function readerWhere(state: SuperTabState, actor: Actor): Prisma.SuperTabDecisionWhereInput {
if (actor.kind === 'person') return { personId: person(state, actor.userId).id }
// A Buddy reads its person's own decisions in its project, by the person's index; each one's conversation is still
// checked as the Buddy reads it (readableIn), so none in a private chat or after its person left (buddies.ts).
const buddy = state.agents.find(a => a.id === actor.agentId && isBuddy(a))
// Never a routing reflection's: those are about the project's routing, for its people (review of #2276).
// A Swarm-wide Buddy reads its person's decisions in every project, each still checked as it reads that conversation
// (Dee, 10-31); a project session and an older Buddy, those of its own project.
if (buddy) return { personId: buddy.buddyOf!.personId, ...(isSwarmBuddy(buddy) ? {} : { projectId: agentProjectId(state, buddy) }), AND: [notReflection] }
const led = ledProject(state, actor.agentId)
return { OR: [{ askerAgentId: actor.agentId }, ...led ? [{ projectId: led.id }] : []] }
}
/** What an access check reads of a conversation (projects.ts canReadGroup), and whether its work is over (workOver). */
const ACCESS_FIELDS = ['id', 'kind', 'projectId', 'audience', 'archived', 'assignment.status'] as const
/** The conversations [ids] names: those the read loaded, and the rest (quiet, archived, or left out of a light read) read
* here, so a decision in one still counts. With [only], the rest bring only those fields. A deleted conversation is none. */
async function conversationsOf(tx: Tx, tabId: string, state: SuperTabState, ids: string[],
only?: readonly string[]): Promise<Map<string, Conversation>> {
const named = new Set(ids)
const found = new Map(state.conversations.filter(c => named.has(c.id)).map(c => [c.id, c]))
const missing = [...named].filter(id => !found.has(id))
if (!missing.length) return found
// By id through its index (parts/indexed.ts): a person's read counts these on each poll.
const rows = await groupsBy(tx, 'key', [{ $match: { tabId, deleted: false, key: { $in: missing } } },
{ $project: { _id: 0, key: 1, ...only ? Object.fromEntries(only.map(field => [`data.${field}`, 1])) : { data: 1 } } }]) as unknown as Array<{ key: string; data: unknown }>
for (const row of rows) found.set(row.key, row.data as Conversation)
return found
}
/** Checked at every read, for agents too: a reader who can no longer read the conversation no longer reads its decisions.
* One asked in a closed Chat with PM stays its person's and the PM's (projects.ts readsRecordsIn). */
const readableIn = (state: SuperTabState, actor: Actor, groups: Map<string, Conversation>, conversationId: string) => {
const group = groups.get(conversationId)
return group && readsRecordsIn(state, actor, group) ? group : undefined
}
/** Answered by the person themself: as `waiting`, a row written before `delegated` has no such field. */
const yours: Prisma.SuperTabDecisionWhereInput = { OR: [{ delegated: { isSet: false } }, { delegated: null }, { delegated: false }] }
/** Answered by someone: not closed unanswered (withdrawIn), which every row from before `withdrawn` was not. */
const notWithdrawn: Prisma.SuperTabDecisionWhereInput = { OR: [{ withdrawn: { isSet: false } }, { withdrawn: null }, { withdrawn: false }] }
/** Which decisions a list holds: those still open, or those answered. `settled` is every answered one, those left to the
* PM included; `answered` is what an older Desktop reads and labels each "You chose", so for a person it leaves out those
* the PM decided (their Chat with PM has the PM's line). An agent's `answered` holds them all, saying who decided. */
export type DecisionList = 'open' | 'answered' | 'settled'
const LIST_PAGE = 200
/** ponytail: the newest LIST_PAGE per list; `more` says when there are others. Page it if a reader ever has more. */
async function readable(tx: Tx, tabId: string, state: SuperTabState, actor: Actor, list: DecisionList) {
const which = list === 'open' ? [waiting] : list === 'answered' && actor.kind === 'person'
? [{ answeredAt: { not: null } }, yours, notWithdrawn] : [{ answeredAt: { not: null } }, notWithdrawn]
const read = await tx.superTabDecision.findMany({ where: { tabId, AND: [readerWhere(state, actor), ...which] },
orderBy: { createdAt: 'desc' }, take: LIST_PAGE + 1 })
const rows = read.slice(0, LIST_PAGE)
const groups = await conversationsOf(tx, tabId, state, rows.map(r => r.conversationId))
return { more: read.length > LIST_PAGE, rows: rows.flatMap(row => {
const group = readableIn(state, actor, groups, row.conversationId)
// An open one whose work is over waits no more, closed or not yet (one from before withdrawIn).
return group && !(list === 'open' && workOver(state, group)) ? [{ row, group }] : []
}) }
}
/** How many of a project's open decisions wait in each conversation for each person, for its digest (digest.ts
* decisionLines): never what they ask. Every open one is read, so every one counts, however many there are, and private
* ones filtered out later never crowd out shared ones (review of #1772). Counted here, reading only who and where:
* groupBy on this model once panicked the Prisma engine on Mongo (review of #1855). */
export async function waitingInProject(tx: Tx, tabId: string, projectId: string): Promise<Array<{ conversationId: string; personId: string; count: number }>> {
const rows = await tx.superTabDecision.findMany({ where: { tabId, projectId, ...waiting }, select: { conversationId: true, personId: true } })
const counts = new Map<string, { conversationId: string; personId: string; count: number }>()
for (const { conversationId, personId } of rows) {
const key = JSON.stringify([conversationId, personId])
const entry = counts.get(key)
if (entry) entry.count++
else counts.set(key, { conversationId, personId, count: 1 })
}
return [...counts.values()]
}
/** A person's open decisions: how many, and a digest of which. A client reads its list again when the digest moves, as
* when one is answered elsewhere and another asked, which leaves the count alone (review of #1820). Read on every poll, so
* only each one's id and conversation, and each quiet conversation's access fields: never what they ask, nor a brief. Not
* capped: a cap counted rows the reader cannot open and left out ones they can, so the badge undercounted. */
export async function decisionsWaiting(tx: Tx, tabId: string, state: SuperTabState,
actor: Extract<Actor, { kind: 'person' }>): Promise<{ count: number; digest: string }> {
const rows = await tx.superTabDecision.findMany({ where: { tabId, AND: [readerWhere(state, actor), waiting] }, select: { id: true, conversationId: true } })
const groups = await conversationsOf(tx, tabId, state, rows.map(r => r.conversationId), ACCESS_FIELDS)
const ids = rows.filter(row => {
const group = readableIn(state, actor, groups, row.conversationId)
return group && !workOver(state, group)
}).map(row => row.id).sort()
return { count: ids.length, digest: createHash('sha256').update(ids.join('\n')).digest('base64url').slice(0, 16) }
}
/** One list of the reader's decisions, newest first, and whether it leaves older ones out (`more`): a client may take a
* decision missing from it as answered or gone only when it does not. */
export async function listDecisions(tx: Tx, tabId: string, state: SuperTabState, actor: Actor, list: DecisionList) {
const { more, rows } = await readable(tx, tabId, state, actor, list)
return { more, decisions: rows.map(({ row, group }) => {
const asker = state.agents.find(a => a.id === row.askerAgentId)
// A Buddy's question about no one project has none ('').
return { id: row.id, batchId: row.batchId, projectId: row.projectId, projectName: projectsOf(state).find(p => p.id === row.projectId)?.name ?? '',
conversationId: row.conversationId, conversationTitle: group.title, assignmentId: row.assignmentId ?? null,
// An agent reads whom it asked by name, never email (review of #2954); the person's own app keeps the email.
personId: row.personId, personEmail: actor.kind === 'agent' ? null : state.people.find(p => p.id === row.personId)?.email ?? null,
personName: agentWrittenNameOf(state, row.personId) ?? null,
askerAgentId: row.askerAgentId, askerName: asker?.displayName ?? asker?.name ?? 'Agent',
question: row.question, options: row.options, recommended: row.recommended, unblocks: row.unblocks,
createdAt: row.createdAt, answeredAt: row.answeredAt ?? null, choice: row.choice ?? null, note: row.note ?? null,
delegated: row.delegated === true, overdue: row.overdue === true, defaultAt: row.defaultAt ?? null, defaulted: row.defaulted === true,
// What the 24-hour sweep can take: the sweep skips required agreement, reflections and an invalid recommended option.
pmTakesOver: row.mustAgree !== true && row.kind !== REFLECTION_DECISION && !isBuddyDecision(row.kind) && row.kind !== PROPOSAL_QUESTION && row.recommended >= 0 && row.recommended < row.options.length,
// A person's own Buddy asked it (no Let PM decide), and whether it is a line waiting to be sent (task #4525).
fromBuddy: isBuddyDecision(row.kind), send: row.kind === BUDDY_SEND,
// A typed answer (no option) reads as its words.
answer: row.choice == null ? (row.answeredAt ? row.note ?? null : null)
: row.options[row.choice] === undefined ? null : row.defaulted ? `Default applied: ${row.options[row.choice]!}` : answerText(row.options[row.choice]!, row.delegated === true) }
}) }
}