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.

17.9 KB
Raw Blame
import { reopenTaskApproval, stageTaskApproval } from './taskApproval.js'
import { steers } from './boardRights.js'
import { expireProposalQuestion } from './proposalClock.js'
export { advanceProposalCards, proposalDueAt } from './proposalClock.js'
/** Durable proposal metadata lives on its existing version-guarded card. Discussion stays in message rows. */
import { z } from 'zod'
import { author, fail, nextConversationNumber, person, stableId, type Actor, type Author, type Conversation, type MessageDraft, renderWorkTask, type SuperTabState } from './model.js'
import { defaultBuddy, isBuddy } from './buddies.js'
import { recordAsked } from './leaderboard/record.js'
import { stampLane } from './dispatch.js'
import { groupProject, ledProject, readConversation, canReadProject, readProject, type SwarmProject } from './projects.js'
import { proposalPriority, type TaskPriority } from './taskPriority.js'

export interface ProposalSender { personId: string; generation: string; buddyId?: string }
export interface ProposalRecord {
  version: 1
  text: string
  goal: string
  scope?: string
  why: string
  doneWhen: string
  evidence: string[]
  priority: TaskPriority
  createdAt: number
  senders: ProposalSender[]
  questions: ProposalQuestion[]
  legacyMessageId?: string
  decision?: { kind: 'accept' | 'reshape' | 'later' | 'no'; reason: string; at: number; by: string; revisitAt?: number }
  mergedInto?: string
  mergedFrom?: string[]
  overdue?: true
  waitSince?: number
}
export interface ProposalQuestion {
  id: string; personId: string; question: string; defaultAnswer: string; deadline: number; requiresConsent: boolean
  answer?: { text: string; at: number; by: string; defaulted?: true }
  overdue?: true
}
const field = z.string().trim().min(1).max(4000)
export const proposalFields = {
  text: z.string().trim().min(1).max(32_000), goal: field, why: field, doneWhen: field,
  evidence: z.array(z.string().trim().min(1).max(2000)).min(1).max(5),
}
export const proposalCreateSchema = z.object({ type: z.literal('proposal.create'), projectId: z.string().min(1).max(160),
  title: z.string().trim().min(1).max(160), ...proposalFields, priority: z.enum(['P0', 'P1', 'P2', 'P3', 'hotfix']) }).strict()
export type CreateProposal = z.infer<typeof proposalCreateSchema>

export function requireBoard(project: SwarmProject): void {
  if (project.boardMode !== true) fail('BOARD_MODE_REQUIRED', 'This project has not switched to proposal cards.', 409)
}
/** Legacy low/normal/high keep their old meaning; only an entitled person can originate a hotfix. */
export function cardPriority(state: SuperTabState, project: SwarmProject, ownerId: string, value: string): TaskPriority {
  const priority = value === 'hotfix' ? 'P0' : /^P[0-3]$/.test(value) ? value as TaskPriority : proposalPriority(value)
  const member = person(state, ownerId)
  if (priority === 'P0' && !steers(state, project, member.id)) {
    fail('PRIORITY_FORBIDDEN', 'Only the project owner, Swarm owner or top decider may propose P0 or a hotfix.', 403)
  }
  return priority
}

export function createProposalCard(state: SuperTabState, project: SwarmProject, sender: ProposalSender,
  input: Omit<CreateProposal, 'type' | 'projectId'>, id: string, now: number, legacyMirror = false): Conversation {
  if (!legacyMirror) requireBoard(project)
  const member = state.people.find(p => p.id === sender.personId && p.generation === sender.generation)
  if (!member || !canReadProject(state, { kind: 'person', userId: member.id, email: member.email }, project)) fail('NOT_FOUND', 'This project is unavailable.', 404)
  const parsed = proposalCreateSchema.parse({ type: 'proposal.create', projectId: project.id, ...input })
  const priority = cardPriority(state, project, member.id, input.priority)
  const leadId = state.conversations.find(c => c.id === project.leadConversationId)?.leadId ?? null
  const number = nextConversationNumber(state)
  state.groupCounter = number
  const card: Conversation = { id, number, projectId: project.id, title: input.title, leadId, agentIds: leadId ? [leadId] : [],
    archived: false, brief: input.text, checks: [], assignment: null, lastMessageSequence: 0, lastActivityAt: new Date(now).toISOString(),
    requesterId: member.id, priority, codePullRequestUrls: [],
    proposal: { version: 1, text: parsed.text, goal: parsed.goal, why: parsed.why, doneWhen: parsed.doneWhen,
      evidence: parsed.evidence, priority, createdAt: now, senders: [sender], questions: [] } }
  stageTaskApproval(state, card, now)
  state.conversations.push(card)
  return card
}
export function authorizePersonProposal(state: SuperTabState, actor: Actor, input: CreateProposal): void {
  if (actor.kind !== 'person') fail('PROPOSAL_PERSON', 'A person proposes from the Board; a Buddy uses buddy.propose with their consent.', 403)
  const project = readProject(state, actor, input.projectId)
  requireBoard(project)
  cardPriority(state, project, actor.userId, input.priority)
}
export function createPersonProposal(state: SuperTabState, actor: Actor, input: CreateProposal, id: string, now: number): Conversation {
  if (actor.kind !== 'person') fail('PROPOSAL_PERSON', 'A person proposes from the Board; a Buddy uses buddy.propose with their consent.', 403)
  authorizePersonProposal(state, actor, input)
  const member = person(state, actor.userId), project = readProject(state, actor, input.projectId)
  return createProposalCard(state, project, { personId: member.id, generation: member.generation }, input, id, now)
}
export function proposalRoot(state: SuperTabState, card: Conversation, id: string, sender: Author): MessageDraft {
  return { id, conversationId: card.id, author: sender, text: card.proposal!.text, replyTo: null,
    recipients: card.leadId ? [card.leadId] : [], source: { kind: 'proposal-card', priority: card.priority } }
}
export const legacyProposalId = (projectId: string, messageId: string): string => stableId('legacy-proposal', projectId, messageId)
export interface LegacyProposalAsk { messageId: string; conversationId: string; personId: string; text: string; at: number; generation?: string }
/** Caller loads this stable id (including dormant cards) before importing; no scan or second interpretation of consent. */
export function importLegacyProposal(state: SuperTabState, project: SwarmProject, ask: LegacyProposalAsk, now: number): string {
  requireBoard(project)
  const id = legacyProposalId(project.id, ask.messageId)
  if (state.conversations.some(c => c.id === id)) return id
  const member = person(state, ask.personId)
  const original = state.conversations.find(c => c.id === ask.conversationId)
  if (!original || original.kind || original.audience || groupProject(state, original).id !== project.id
    || (ask.generation && member.generation !== ask.generation)) fail('NOT_FOUND', 'The original request is unavailable.', 404)
  const card = createProposalCard(state, project, { personId: member.id, generation: member.generation }, {
    title: ask.text.trim().slice(0, 160) || 'Earlier request', text: ask.text, goal: ask.text.slice(0, 4000),
    why: 'Imported unanswered request; details remain to be clarified.', doneWhen: 'To be clarified on this card.',
    evidence: ['Original project message'], priority: 'P2',
  }, id, now)
  card.proposal!.legacyMessageId = ask.messageId
  card.proposal!.createdAt = ask.at
  return id
}

export const MAX_CARD_QUESTIONS = 20
export const MAX_CARD_SENDERS = 50
export type ProposalAction =
  | { type: 'proposal.decide'; conversationId: string; decision: 'accept' | 'reshape' | 'later' | 'no'; reason: string;
      task?: import('./model.js').WorkTask; checks?: Array<{ description: string; independent?: boolean }>; revisitAt?: number }
  | { type: 'proposal.ask'; conversationId: string; personId: string; question: string; defaultAnswer: string; deadline: number; requiresConsent?: boolean }
  | { type: 'proposal.answer'; conversationId: string; questionId: string; text: string }
  | { type: 'proposal.merge'; conversationId: string; intoConversationId: string; reason: string }

function namedCard(state: SuperTabState, actor: Actor, id: string): Conversation & { proposal: ProposalRecord } {
  const group = readConversation(state, actor, id)
  if (!group.proposal || group.kind || group.audience) fail('NOT_FOUND', 'This proposal is unavailable.', 404)
  return group as Conversation & { proposal: ProposalRecord }
}
function currentSender(state: SuperTabState, card: Conversation & { proposal: ProposalRecord }, personId: string): ProposalSender[] {
  const member = state.people.find(p => p.id === personId)
  return member ? card.proposal.senders.filter(s => s.personId === member.id && s.generation === member.generation) : []
}
function answerer(state: SuperTabState, actor: Actor, card: Conversation & { proposal: ProposalRecord }, questionId: string): ProposalQuestion {
  const q = card.proposal.questions.find(q => q.id === questionId) ?? fail('NOT_FOUND', 'This question is unavailable.', 404)
  const senders = currentSender(state, card, q.personId)
  const self = actor.kind === 'agent' ? state.agents.find(a => a.id === actor.agentId && isBuddy(a)) : undefined
  const own = actor.kind === 'person' ? actor.userId === q.personId : !!self && self.buddyOf!.personId === q.personId
    && senders.some(s => s.generation === self.buddyOf!.generation && (s.buddyId === self.id ||
      ((!s.buddyId || !state.agents.some(a => a.id === s.buddyId && a.buddyOf?.personId === s.personId && a.buddyOf.generation === s.generation))
        && defaultBuddy(state, s.personId)?.id === self.id)))
  if (!senders.length || !own) fail('PROPOSAL_ANSWER_FORBIDDEN', 'Only the person asked or the Buddy that sent this card may answer.', 403)
  if (q.requiresConsent && actor.kind !== 'person') fail('PROPOSAL_CONSENT_REQUIRED', 'This question needs the named person’s own agreement.', 403)
  return q
}
/** Called before receipt replay as well as apply; a recorded operation retains no revoked right. */
export function authorizeProposalAction(state: SuperTabState, actor: Actor, command: ProposalAction): void {
  const card = namedCard(state, actor, command.conversationId), project = groupProject(state, card)
  if (command.type === 'proposal.answer') { answerer(state, actor, card, command.questionId); return }
  if (actor.kind !== 'agent' || ledProject(state, actor.agentId)?.id !== project.id) fail('COORDINATOR_REQUIRED', 'Only this project’s current PM decides, asks or merges proposals.', 403)
  if (command.type === 'proposal.merge') {
    const target = namedCard(state, actor, command.intoConversationId)
    if (groupProject(state, target).id !== project.id) fail('NOT_FOUND', 'This proposal is unavailable.', 404)
  }
}

function pending(card: Conversation & { proposal: ProposalRecord }): void {
  if (card.proposal.decision || card.proposal.mergedInto) fail('PROPOSAL_DECIDED', 'This proposal already has a decision or was merged.', 409)
}
const hasOpenQuestion = (card: Conversation & { proposal: ProposalRecord }) => card.proposal.questions.some(q => !q.answer)

export function applyProposalAction(state: SuperTabState, actor: Actor, command: ProposalAction, operationId: string, now: number):
  { messages: MessageDraft[]; result: Record<string, unknown> } {
  authorizeProposalAction(state, actor, command)
  const card = namedCard(state, actor, command.conversationId), sender = author(state, actor)
  const messages: MessageDraft[] = []
  const result: Record<string, unknown> = { conversationId: card.id, messageId: operationId }
  const row = (text: string, source: Record<string, unknown>, recipients: string[] = [], id = operationId) =>
    messages.push({ id, conversationId: card.id, author: sender, text, recipients, replyTo: null, source })
  if (command.type === 'proposal.answer') {
    const q = answerer(state, actor, card, command.questionId)
    messages.push(...expireProposalQuestion(state, card, q, now))
    result.applied = !q.answer
    if (!q.answer) q.answer = { text: command.text, at: now, by: sender.id }
    row(command.text, { kind: 'proposal-answer', questionId: q.id, applied: result.applied }, card.leadId ? [card.leadId] : [])
  } else if (command.type === 'proposal.ask') {
    pending(card)
    if (!currentSender(state, card, command.personId).length) fail('PROPOSAL_ANSWER_FORBIDDEN', 'Ask a current proposer on this card.', 403)
    if (command.deadline <= now) fail('PROPOSAL_DEADLINE', 'Choose a future deadline.', 400)
    if (card.proposal.questions.length >= MAX_CARD_QUESTIONS) fail('PROPOSAL_LIMIT', 'This card has 20 questions; decide it or reshape a new proposal.', 409)
    const q: ProposalQuestion = { id: operationId, personId: command.personId, question: command.question, defaultAnswer: command.defaultAnswer,
      deadline: command.deadline, requiresConsent: command.requiresConsent ?? false }
    card.proposal.questions.push(q)
    result.questionId = q.id
    // On the card alone: no line in the proposer's private chat with their own agent (task #4558). One that needs their own
    // agreement has no default to fall back on, so it tags them there: their inbox and phone, with or without a Buddy.
    row(`${q.question}\nDefault: ${q.defaultAnswer}\nBy: ${new Date(q.deadline).toISOString()}`, { kind: 'proposal-question', questionId: q.id })
    if (q.requiresConsent) messages.at(-1)!.mentions = [q.personId]
  } else if (command.type === 'proposal.decide') {
    pending(card)
    if (hasOpenQuestion(card)) fail('PROPOSAL_QUESTION_OPEN', 'Answer the open questions before deciding.', 409)
    if (command.decision === 'later' && (!command.revisitAt || command.revisitAt <= now)) fail('PROPOSAL_DATE', 'Later needs a future revisit date.', 400)
    if (command.decision === 'accept' || command.decision === 'reshape') {
      if (!command.task || !command.checks?.length) fail('TASK_CONTRACT_MISSING', 'Accepted work needs its task and done-when checks.', 400)
      card.task = command.task
      card.brief = renderWorkTask(command.task)
      card.briefAt = now
      card.stepIds = []
      card.checks = command.checks.map((check, i) => ({ id: stableId(operationId, 'check', String(i)), description: check.description, independent: check.independent ?? false, evidence: null, passedBy: null, verdicts: [] }))
      stampLane(card)
      recordAsked(card, card.requesterId, now)
      // The person approves the task the PM shaped: an approval stored before this decision never carries over.
      reopenTaskApproval(card)
    }
    card.proposal.decision = { kind: command.decision, reason: command.reason, at: now, by: sender.id,
      ...(command.decision === 'later' ? { revisitAt: command.revisitAt } : {}) }
    delete card.proposal.overdue
    if (command.decision === 'no') card.archived = true
    row(`${command.decision}: ${command.reason}`, { kind: 'proposal-decision', decision: command.decision })
  } else {
    if (card.taskApproval) fail('TASK_APPROVAL_REQUIRED', 'Keep Review proposals separate so each person’s decision and chosen agent stay attached.', 409)
    pending(card)
    const target = namedCard(state, actor, command.intoConversationId)
    if (target.taskApproval) fail('TASK_APPROVAL_REQUIRED', 'Keep Review proposals separate so each person’s decision and chosen agent stay attached.', 409)
    pending(target)
    if (target.id === card.id) fail('PROPOSAL_MERGE_SELF', 'Merge another proposal into this card.', 400)
    if (hasOpenQuestion(card)) fail('PROPOSAL_QUESTION_OPEN', 'Answer the source card’s questions before merging.', 409)
    const senders = [...target.proposal.senders, ...card.proposal.senders].filter((s, i, all) =>
      all.findIndex(p => p.personId === s.personId && p.generation === s.generation && p.buddyId === s.buddyId) === i)
    const mergedFrom = [...new Set([...target.proposal.mergedFrom ?? [], card.id, ...card.proposal.mergedFrom ?? []])]
    if (senders.length > MAX_CARD_SENDERS || mergedFrom.length > MAX_CARD_SENDERS) fail('PROPOSAL_LIMIT', 'A combined card holds at most 50 senders and merged cards.', 409)
    for (const id of card.proposal.mergedFrom ?? []) {
      const child = namedCard(state, actor, id)
      if (child.proposal.mergedInto !== card.id) fail('PROPOSAL_MERGE_STALE', 'A merged card changed; read the cards again.', 409)
      child.proposal.mergedInto = target.id
    }
    target.proposal.senders = senders
    target.proposal.mergedFrom = mergedFrom
    card.proposal.mergedInto = target.id
    card.archived = true
    row(`Merged into #${target.number}: ${command.reason}`, { kind: 'proposal-merged', intoConversationId: target.id })
    messages.push({ id: stableId(operationId, 'merge-target'), conversationId: target.id, author: sender, text: `Merged #${card.number}: ${command.reason}`,
      recipients: target.leadId ? [target.leadId] : [], replyTo: null, source: { kind: 'proposal-merged' } })
    result.conversationId = target.id
  }
  return { messages, result }
}

/** Server-written sources are the only notices. A raw chat line never enters a switched PM's delivery queue. */
export function pmAcceptsMessage(state: SuperTabState, recipientId: string, source: unknown): boolean {
  const project = ledProject(state, recipientId)
  return !project?.boardMode || !!source && typeof source === 'object' && typeof (source as { kind?: unknown }).kind === 'string'
}

/** Verified originals are supplied by the store in bounded primary-key batches. Keep every other ask owed. */
export function migrateLegacyProposals(state: SuperTabState, project: SwarmProject, originals: LegacyProposalAsk[], now: number): MessageDraft[] {
  const messages: MessageDraft[] = []
  for (const ask of originals) {
    const id = legacyProposalId(project.id, ask.messageId)
    const existed = state.conversations.some(c => c.id === id)
    importLegacyProposal(state, project, ask, now)
    if (!existed) {
      const card = state.conversations.find(c => c.id === id)!
      messages.push(proposalRoot(state, card, stableId(id, 'root'), author(state, { kind: 'person', userId: ask.personId, email: '' })))
    }
    const original = state.conversations.find(c => c.id === ask.conversationId)!
    original.owed = (original.owed ?? []).filter(a => a.id !== ask.messageId)
    if (!original.owed.length) delete original.owed
  }
  return messages
}