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.

16.9 KB
Raw Blame
/**
 * An instructions save keeps the rules people gave (task #3151, Ken 11-05, from lamp). A PM's tidy dropped Leo's rule, judging
 * it impossible without asking him, and the "(0xken15, 4 Nov)" of a rule it kept; nothing checked the save. Now a save that
 * drops a rule, or who gave it (instructionsDiff.ts droppedRules), is refused with the list, unless each person of each
 * dropped rule makes the save or wrote a message approving it that the save names. Who a person is comes from the sender or
 * the stored message's author, never the caller's word (askedBy). The approver is then told in one private line.
 */
import { attributedRules, budgetParts, droppedRules, INSTRUCTIONS_BUDGET, ITEM_CHARS, keptIn, MAX_REPEATS, personKey, removedItems, repeatedRules,
  type DroppedRule, type InstructionsBudget, type RulePlace } from './instructionsDiff.js'
import { fail, type Author, type Conversation, type SuperTabState } from './model.js'
import { canReadProject, projectRules, type SwarmProject } from './projects.js'
import { isSwarmBuddyChat } from './buddies.js'
import type { ProjectRules } from './policy.js'
import { agentWrittenNameOf } from './personNames.js'
import { swarmUsernames } from './usernames.js'

/** Approval messages one save may name: one per person whose rules it drops is plenty. */
export const MAX_APPROVALS = 20
/** Characters of one rule in a refusal or a notice; a longer one is cut. */
const RULE_CHARS = 300

/** A message a save names as a person's approval, as the store loads it by id in this tab. */
export interface ApprovalRow { id: string; author: Author; source: boolean; createdAt: number; conversationId: string }

/** The members a written name is: by username, shown name or email, else by one word of a shown name ("Leo" is Leo Tran),
 *  honorifics and a possessive aside (instructionsDiff.ts personKey). */
export function membersNamed(state: SuperTabState, name: string, authority?: ProjectRules['instructionApprovals']): string[] {
  const key = personKey(name)
  if (!key) return []
  // Explicit identity links outrank mutable display names. Only listed IDs gain the extra identity.
  const present = new Set(state.people.map(p => p.id))
  const linked = authority?.people.find(p => personKey(p.name) === key)
  if (linked) return linked.accountIds.filter(id => present.has(id))
  const usernames = swarmUsernames(state)
  // A linked account's unique handle/email may name the group too. Display names never add an account to that group.
  const account = state.people.find(p => [usernames.get(p.id), p.email].some(n => n && personKey(n) === key))
  const accountLink = account && authority?.people.find(p => p.accountIds.includes(account.id))
  if (accountLink) return accountLink.accountIds.filter(id => present.has(id))
  const whole = state.people.filter(p => [usernames.get(p.id), p.name, p.email, p.email.split('@')[0]].some(n => n && personKey(n) === key))
  if (whole.length) return whole.map(p => p.id)
  return state.people.filter(p => p.name?.split(/\s+/).some(word => personKey(word) === key)).map(p => p.id)
}

const cut = (text: string) => [...text].length <= RULE_CHARS ? text : `${[...text].slice(0, RULE_CHARS - 1).join('')}…`
const WHY: Record<DroppedRule['why'], string> = {
  removed: 'removed',
  unattributed: 'kept without who gave it',
  changed: 'changed beyond a rewording, so its meaning may differ',
  waiting: 'moved to a code task the Swarm has not seen merged on GitHub',
}

/**
 * Where this project's people's rules may have moved (task #3392): its rules record, by who asked for each, and its code
 * tasks (a task's brief; not a step, a chat or a task cancelled unmerged), a task counting once the Swarm read its pull
 * request merged on GitHub. A task that went
 * quiet is in the state only when the save names it (tasks), which loads it.
 */
function rulePlaces(state: SuperTabState, project: SwarmProject, merges: Readonly<Record<string, number | null>>): RulePlace[] {
  // Merged only as GitHub itself says, read by the store before this save ([merges]), never by the task's own merge record,
  // which any agent of the project writes with any link (River, review of #3220); and only after the rule went into its brief
  // (briefAt): an older merge never carried it (#3463). A task from before briefAt counts any merge, as it did.
  const seenMerged = (c: Conversation) => (c.pullRequestUrls ?? []).some(url => {
    const at = merges[url]
    return typeof at === 'number' && (c.briefAt === undefined || at > c.briefAt)
  })
  const records = projectRules(state, project.id).map(r => ({ text: r.text, people: [r.askedBy], where: 'the rules record', open: false }))
  const tasks = codeTasks(state, project).filter(c => seenMerged(c) || c.assignment?.status !== 'cancelled')
    .map(c => ({ text: c.brief, people: [], where: c.number ? `task #${c.number}` : `task "${c.title}"`, open: !seenMerged(c) }))
  return [...records, ...tasks]
}

/** The project's code tasks: its tasks with a brief, not a step, a chat or a private chat (rulePlaces, tasksHoldingMoves). */
const codeTasks = (state: SuperTabState, project: SwarmProject): Conversation[] => state.conversations.filter(c => (c.projectId ?? 'lead') === project.id
  && c.id !== project.leadConversationId && !c.kind && !c.reviewOf && !c.step && !c.audience && !!c.brief)

/** How the guard tells people apart in this Swarm: a written name as the members it is, so "0xken15" and "Ken" are one. */
function identifier(state: SuperTabState, authority?: ProjectRules['instructionApprovals']): (name: string) => string {
  const membersOf = new Map<string, string[]>()
  return name => (membersOf.get(name) ?? membersOf.set(name, membersNamed(state, name, authority)).get(name)!).slice().sort().join(',') || `?${personKey(name)}`
}

/**
 * The project's code tasks a save from [before] to [after] would move a person's rule into, as the guard itself reads a move
 * (droppedRules): each task alone, counted open, that holds a rule the save drops, across wrapped lines or as one rule of a
 * line of several, with the guard's own words (filler words, word endings: review 2 of #3273). The store reads their pull
 * requests' merges before the save (store.ts pullRequestMergesFor, #3463). It runs only for a save that drops a person's rule,
 * once per code task: a few dozen in a project.
 */
export function tasksHoldingMoves(state: SuperTabState, project: SwarmProject, before: string, after: string): Conversation[] {
  const identify = identifier(state)
  const lost = droppedRules(before, after, identify)
  if (!lost.length) return []
  return codeTasks(state, project).filter(task =>
    droppedRules(before, after, identify, [{ text: task.brief, people: [], where: task.id, open: true }]).some(rule => rule.movedTo === task.id))
}

/**
 * The rules [after] drops from [before] that their people allowed, by the person to tell, and those rules: refused with the
 * list when any is not allowed. A person allows their rule by making the save themselves (no notice: they know) or by a
 * message of their own among [approvals] (the store's rows) that [named] lists: a person's, not relayed by a Buddy or the Swarm
 * (source), written after [since] (when the revision being replaced was saved) in a conversation of this project. A rule of
 * several people needs each of them. A name that is no member is the project owner's to allow.
 */
export function allowedDrops(state: SuperTabState, project: SwarmProject, before: string, after: string, sender: { kind: Author['kind']; id: string },
  named: readonly string[], approvals: readonly ApprovalRow[], since: number, merges: Readonly<Record<string, number | null>> = {}, authority?: ProjectRules['instructionApprovals']): { told: Map<string, DroppedRule[]>; rules: DroppedRule[]; deciderId?: string } {
  const told = new Map<string, DroppedRule[]>()
  const membersOf = new Map<string, string[]>()
  const members = (name: string) => membersOf.get(name) ?? membersOf.set(name, membersNamed(state, name, authority)).get(name)!
  const dropped = droppedRules(before, after, identifier(state, authority), rulePlaces(state, project, merges))
  if (!dropped.length) return { told, rules: [] }
  const saver = sender.kind === 'person' ? sender.id : undefined
  // Written after the revision this save replaces, in a conversation of this project: an old "thanks" approves nothing (review
  // of #3112). A person's one Buddy chat belongs to no project.
  const here = (conversationId: string) => conversationId === project.leadConversationId || state.conversations.some(c => c.id === conversationId
    && !isSwarmBuddyChat(c) && (c.projectId ?? 'lead') === project.id)
  const eligible = (id: string) => state.people.some(p => p.id === id && canReadProject(state, { kind: 'person', userId: p.id, email: p.email }, project))
  const approvers = new Set(approvals.filter(a => named.includes(a.id) && a.author.kind === 'person' && !a.source && a.createdAt >= since
    && here(a.conversationId)).map(a => a.author.id)
    .filter(eligible))
  const decider = authority?.topDeciderId && approvers.has(authority.topDeciderId) ? authority.topDeciderId : undefined
  const refused: DroppedRule[] = []
  for (const rule of dropped) {
    const by = decider ? [decider] : rule.people.map(name => {
      const ids = members(name).length ? members(name) : [project.ownerId]
      if (saver && ids.includes(saver)) return saver
      return ids.find(id => approvers.has(id))
    })
    if (by.some(id => !id)) { refused.push(rule); continue }
    // With a decider override the rule's authors did not approve it themselves: tell their current, permitted accounts too.
    const notify = decider ? [...by, ...rule.people.flatMap(members).filter(eligible)] : by
    for (const id of new Set(notify as string[])) if (id !== saver) told.set(id, [...told.get(id) ?? [], rule])
  }
  if (refused.length) {
    const unknown = (rule: DroppedRule) => rule.people.filter(name => !members(name).length)
    fail('INSTRUCTIONS_RULES_DROPPED', [
      'Not saved: this drops rules people gave. Keep each rule and who gave it, or move it word for word with who gave it: into '
        + 'people notes or its role section, into the project\'s rules record, or into a code task, whose line stays until the '
        + 'Swarm sees that task\'s pull request merged on GitHub (name a quiet one in tasks). Otherwise ask that person and name their own message approving the change '
        + '(approvals). Never drop or weaken a person\'s rule on your own judgment, even one you think cannot be done.',
      ...(authority?.topDeciderId ? [`The project's top decider ${agentWrittenNameOf(state, authority.topDeciderId) ?? 'named in its rules record'} may also approve any rule with their own recent message in this project.`] : []),
      ...refused.map(rule => `- "${cut(rule.text)}" (${rule.people.join(', ')}): ${WHY[rule.why]}`
        + (rule.movedTo ? ` (${rule.movedTo}): keep its line until it merges.` : '.')
        + (unknown(rule).length ? ` ${unknown(rule).join(', ')} is no member here, so the project's owner decides.`
          : ` Ask ${rule.people.map(name => members(name).map(id => agentWrittenNameOf(state, id) ?? name).join(' or ')).join(' and ')} for approval.`)),
    ].join('\n'), 409, { dropped: refused.map(rule => ({ rule: rule.text, people: rule.people, why: rule.why,
      ...rule.movedTo ? { movedTo: rule.movedTo } : {} })) })
  }
  return { told, rules: dropped, ...decider ? { deciderId: decider } : {} }
}

/**
 * Refuses a save that adds a line repeating one the document keeps (task #3283, Leo 11-05, from lamp: a PM saved a rule the
 * instructions already had as if new, which hid that it had skipped it; #3568, anh Dee 11-06: also the same rule in other
 * words, instructionsDiff.ts repeatedRules). Each repeat is listed with the existing line quoted; a change meant is made on
 * that line. A person may keep both by giving a reason (repeatReason, [forced]); the coordinator never does.
 */
export function refuseRepeats(before: string, after: string, forced = false): void {
  if (forced) return
  const repeats = repeatedRules(before, after)
  if (!repeats.length) return
  const shown = repeats.slice(0, MAX_REPEATS)
  fail('INSTRUCTIONS_RULE_REPEATED', [
    'Not saved: this adds a line that says what the instructions already say, so it would be read twice. Check that rule before '
      + 'adding it: it may be one you skipped. If you meant to change it, change that line in place instead of adding another. '
      + 'Only a member who means to keep both lines saves them, giving a reason (repeatReason).',
    ...shown.map(repeat => `- Existing line: "${cut(repeat.existing)}" (added again as "${cut(repeat.added)}")`),
    ...(repeats.length > shown.length ? [`- And ${repeats.length - shown.length} more.`] : []),
  ].join('\n'), 409, { repeated: shown })
}

const kb = (bytes: number) => `${(bytes / 1024).toFixed(1)} KB`
const partName = (part: string) => part === 'core' ? 'Core' : part === 'people notes' ? 'People notes' : part === 'total' ? 'Whole document'
  : `Role section ${part.slice('role '.length)}`

/**
 * Refuses a save that makes a part of the instructions bigger than its budget (task #3392, anh Dee 11-05, decision 5): core,
 * each role section, people notes and the whole document (instructionsDiff.ts budgetParts), each named with its size, its budget
 * and its size before. A part over budget already, as documents were when this came in, may be saved smaller or unchanged:
 * that is the way down, never blocked.
 */
export function refuseOverBudget(before: string, after: string, budget: InstructionsBudget = INSTRUCTIONS_BUDGET): void {
  const was = new Map(budgetParts(before, budget).map(p => [p.part, p.bytes]))
  const over = budgetParts(after, budget).filter(p => p.bytes > p.budget && p.bytes > (was.get(p.part) ?? 0))
    .map(p => ({ ...p, before: was.get(p.part) ?? 0 }))
  if (!over.length) return
  fail('INSTRUCTIONS_OVER_BUDGET', [
    'Not saved: this makes the instructions bigger than their budget. Make it smaller: a rule the Swarm can check becomes a code '
      + 'task instead of a line; a person\'s rule moves word for word, with who gave it, into people notes or its role section; a '
      + 'step or date that passed goes. A part already over budget may be saved as long as it does not grow.',
    ...over.map(p => `- ${partName(p.part)}: ${kb(p.bytes)} of ${kb(p.budget).replace('.0 KB', ' KB')} (was ${kb(p.before)}).`),
  ].join('\n'), 409, { parts: over })
}

/** Lines one revision's History keeps (River, 11-05): a rewrite of the whole document lists its first 500. */
export const MAX_DROPPED_LINES = 500
/** How the coordinator sorted a line it dropped (pmSchedule.ts, the daily tidy): kept elsewhere with who said it, or a step
 *  or date that passed. `rule`: a person's rule, dropped with their approval. `unsorted`: nobody said, and its words are not
 *  kept elsewhere; listed so the History never hides a line. */
export type DropKind = 'merged' | 'expired' | 'rule' | 'unsorted'
export interface DroppedLine { text: string; kind: DropKind; people: string[] }
/** What a save may say of the lines it drops: a line's words, or enough of them to find it, and its kind. */
export interface SortedLine { text: string; kind: Exclude<DropKind, 'unsorted'> }

const words = (text: string) => text.normalize('NFKC').toLowerCase().replace(/\s+/g, ' ').trim()

/**
 * Every line [after] dropped from [before], for the revision's History, now that the instruction-change line leaves the chat
 * (#3101): each with who gave it and its kind. A person's rule dropped with their approval ([rules], allowedDrops) is `rule`,
 * whatever it was called. Otherwise the kind the save gave the line ([sorted]: its words, or a part of them), else `merged`
 * when its words are all in one line of [after], else `unsorted`.
 */
export function droppedLines(before: string, after: string, sorted: readonly SortedLine[], rules: readonly DroppedRule[]): DroppedLine[] {
  const kept = keptIn(after)
  const named = sorted.map(line => ({ key: words(line.text), kind: line.kind })).filter(line => line.key)
  return removedItems(before, after).slice(0, MAX_DROPPED_LINES).map(text => {
    const key = words(text)
    const people = [...new Set(attributedRules(text).flatMap(rule => rule.people))]
    const kind: DropKind = rules.some(rule => text.includes(rule.text)) ? 'rule'
      : named.find(line => key.includes(line.key))?.kind ?? (kept(text) ? 'merged' : 'unsorted')
    return { text: [...text].length <= ITEM_CHARS ? text : `${[...text].slice(0, ITEM_CHARS - 1).join('')}…`, kind, people }
  })
}

/** The one line a person is told when [who] changed [rules], naming the decider when someone else approved the change. */
export function approvedDropNotice(who: string, project: SwarmProject, rules: readonly DroppedRule[], decider?: string): string {
  const each = rules.map(rule => `${rule.why === 'removed' ? 'removed' : 'changed'} "${cut(rule.text)}"`).join('; ')
  return `${who} changed ${decider ? 'the' : 'your'} ${rules.length === 1 ? 'rule' : `${rules.length} rules`} in the ${project.name} instructions, ${decider ? `approved by ${decider}` : 'as you approved'}: ${each}.`
    .replace(/\s*[\r\n]+\s*/g, ' ')
}