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.

12.7 KB
Raw Blame
/**
 * Gives every project from before instructions its document (design docs/plans/2026-10-30-project-instructions-design.md,
 * Migration). Never run by the server: scripts/swarm-instructions/migrate.ts runs it, a dry run unless `--apply`, after the
 * backend that knows instructions is deployed.
 *
 * Per project without a document: a built-in skill set gets a copy of the template; a custom role set gets one section per
 * role, under the role's name and in its own text, then the template's Workflow and Routing. The project's rules, and the
 * routing policy's notes and differences from the built-in policy, follow under Routing: the owner's words where they
 * exist, a plain sentence where they do not. Nothing is cut for length (the 64 KB limit is a save's). Open tasks' machine
 * and device requirements are not written: the route shows them on their task until it closes.
 *
 * A project that has a document (revision 1 or later, new projects included) is left alone, so a second run writes
 * nothing. Old rules, policy and role texts stay where they are, unread by the new code, for one release.
 */
import type { Prisma, PrismaClient } from '@prisma/client'
import { clock, guardedWrite, loadAll, reassemble, type HeadData } from '../parts/index.js'
import { swarmTransaction } from '../cache.js'
import { stableId, type SuperTabState } from '../model.js'
import { placeRules, projectRules, projectsOf, skillSetOf, type SwarmProject } from '../projects.js'
import type { SwarmRule } from '../rules.js'
import { DEFAULT_ROUTING_POLICY, effectivePolicy, type RoutingModel, type RoutingPolicy } from '../routingPolicy.js'
import { instructionsHash } from '../instructions.js'
import { INSTRUCTIONS_TEMPLATE, TEMPLATE_INTRO, TEMPLATE_ROUTING, TEMPLATE_WORKFLOW } from '../instructionsTemplate.js'
import { writeInstructions } from '../instructionsStore.js'

type Transaction = Prisma.TransactionClient
const TRANSACTION = { maxWait: 5_000, timeout: 60_000 }
export const MIGRATION_SUMMARY = 'Built from this project\'s skills, rules and routing settings.'

export interface MigrationSource {
  project: SwarmProject
  /** A custom set's stored role texts, by role id (SuperTabRoleText). */
  roleTexts: Record<string, string>
  /** The Swarm's rules: only the project's own are written. */
  rules: SwarmRule[]
  /** The Swarm's effective routing policy (its owner's account policy with the Swarm's override). */
  policy: RoutingPolicy
}

const ENGINES: Record<string, string> = { claude: 'Claude', codex: 'Codex' }
const rowName = (row: Pick<RoutingModel, 'engine' | 'model' | 'effort'>) =>
  `${ENGINES[row.engine] ?? row.engine} ${row.model === 'default' ? 'default model' : row.model} at ${row.effort} effort`
const sameRow = (a: Pick<RoutingModel, 'engine' | 'model' | 'effort'>, b: Pick<RoutingModel, 'engine' | 'model' | 'effort'>) =>
  a.engine === b.engine && a.model === b.model && a.effort === b.effort

/** Default rows a saved policy may still hold from before the default table changed: the old row as it was, and the row
 *  that replaced it. Ken, 2026-11-02 turned Sonnet on at high effort; until then the default row was Sonnet at medium,
 *  off. A policy saved before holds the old row unchanged and lacks the new one, and neither is a choice of its owner's. */
const REPLACED_DEFAULTS: ReadonlyArray<{ old: RoutingModel; now: Pick<RoutingModel, 'engine' | 'model' | 'effort'> }> = [
  { old: { engine: 'claude', model: 'sonnet', effort: 'medium', quality: 2, cost: 2, enabled: false }, now: { engine: 'claude', model: 'sonnet', effort: 'high' } },
]

/** The policy's settings that differ from the built-in policy, each as one sentence. */
function policyLines(policy: RoutingPolicy): string[] {
  const current = effectivePolicy(null, null).policy, lines: string[] = []
  // A policy saved with a replaced default row is read against the default it was saved with.
  const replaced = REPLACED_DEFAULTS.filter(r => policy.models.some(m => sameRow(m, r.old)) && !policy.models.some(m => sameRow(m, r.now)))
  const base = { ...current, models: [...current.models.filter(m => !replaced.some(r => sameRow(m, r.now))), ...replaced.map(r => r.old)] }
  if (policy.notes.trim()) lines.push(`Routing notes: ${policy.notes.trim()}`)
  for (const row of policy.models) {
    const built = base.models.find(m => sameRow(m, row))
    if (!built) lines.push(row.enabled ? `${rowName(row)} is offered at strength ${row.quality} of 3, cost ${row.cost}.` : `${rowName(row)} is off.`)
    else {
      if (built.enabled !== row.enabled) lines.push(`${rowName(row)} is ${row.enabled ? 'on' : 'off'}.`)
      if (built.quality !== row.quality || built.cost !== row.cost) lines.push(`${rowName(row)} counts as strength ${row.quality} of 3 at cost ${row.cost}.`)
    }
  }
  for (const row of base.models) if (!policy.models.some(m => sameRow(m, row))) lines.push(`${rowName(row)} is not offered.`)
  for (const level of ['low', 'medium', 'high'] as const) {
    if (policy.floor[level] !== base.floor[level]) lines.push(`Work of ${level} difficulty needs a model of strength ${policy.floor[level]} of 3 or more.`)
  }
  if (policy.quotaReserve !== base.quotaReserve) lines.push(`Keep ${policy.quotaReserve}% of each engine's quota in reserve.`)
  const local = policy.localModels ?? base.localModels!, builtLocal = base.localModels!
  if (local.enabled !== builtLocal.enabled) lines.push(`Models on the Swarm's grid are ${local.enabled ? 'on' : 'off'}.`)
  if (local.quality !== builtLocal.quality) lines.push(`A model on the Swarm's grid counts as strength ${local.quality} of 3 unless it is named here.`)
  const named = local.models ?? [], builtNamed = builtLocal.models ?? []
  for (const row of named) {
    if (!builtNamed.some(m => m.model === row.model && m.quality === row.quality)) lines.push(`Grid model ${row.model} counts as strength ${row.quality} of 3.`)
  }
  for (const row of builtNamed) if (!named.some(m => m.model === row.model)) lines.push(`Grid model ${row.model} has no strength of its own.`)
  for (const row of policy.priorOverrides ?? []) lines.push(`For ${row.kind} work, ${row.model} counts as strength ${row.quality} of 3.`)
  return lines
}

/** A custom role's start default (projects.ts RoleDefaults), which the instructions' routing now carries. */
const defaultsLine = (name: string, defaults: NonNullable<NonNullable<SwarmProject['roles']>[number]['defaults']>) =>
  `${name} runs on ${ENGINES[defaults.engine]} ${defaults.model ?? 'default model'}${defaults.effort ? ` at ${defaults.effort} effort` : ''} unless its start names another.`

/** The document [source]'s project gets. Pure: the same source always gives the same text. */
export function documentFor(source: MigrationSource): { from: 'template' | 'custom'; text: string } {
  const { project } = source
  const custom = skillSetOf(project) === 'custom' ? project.roles ?? [] : null
  const lines = [
    ...source.rules.filter(r => r.projectId === project.id).map(r => r.text),
    ...policyLines(source.policy),
    ...(custom ?? []).flatMap(role => role.defaults ? [defaultsLine(role.name, role.defaults)] : []),
  ]
  const body = custom
    ? [TEMPLATE_INTRO, `## Roles\n\n${custom.map(role => `### ${role.name}\n\n${source.roleTexts[role.id] ?? ''}`.trimEnd()).join('\n\n')}`,
      TEMPLATE_WORKFLOW, TEMPLATE_ROUTING].join('\n\n')
    : INSTRUCTIONS_TEMPLATE.trimEnd()
  if (!custom && !lines.length) return { from: 'template', text: INSTRUCTIONS_TEMPLATE }
  const added = lines.length ? `\n\nFrom this project's rules and routing settings before these instructions:\n\n${lines.map(line => `- ${line}`).join('\n')}` : ''
  return { from: custom ? 'custom' : 'template', text: `${body}${added}\n` }
}

export interface MigratedDocument { tabId: string; projectId: string; from: 'template' | 'custom'; bytes: number; text: string }
export interface InstructionsMigrationReport {
  apply: boolean
  /** Swarms in parts that were read. */
  swarms: number
  /** Documents written, or in a dry run to be written, with their text. */
  documents: MigratedDocument[]
  /** Projects that already have a document: left alone. */
  alreadyDone: number
  /** Swarms not in parts yet: they get their documents when they are migrated, then rerun. */
  skipped: string[]
  failed: Array<{ tabId: string; error: string }>
}

/** The report as the script prints it: each document's project, origin and size, its text only for the Swarm named in
 *  [textOf]. A document holds its team's private role texts and rules, and a run against production prints into an
 *  operator's or agent's transcript (review of phase 2). */
export function printableReport(report: InstructionsMigrationReport, opts: { textOf?: string } = {}) {
  return { ...report, documents: report.documents.map(({ text, ...document }) => document.tabId === opts.textOf ? { ...document, text } : document) }
}

interface Plan { headVersion: number; head: HeadData; headFields: { groupCounter: number; visibilityEpoch: number; sequenceBase: number }
  projects: SwarmProject[]; documents: Array<MigratedDocument & { project: SwarmProject }>; alreadyDone: number }

/** What one Swarm's projects would get, read in [tx] (or straight from the database for a dry run). */
async function planSwarm(tx: Transaction, tabId: string): Promise<Plan> {
  const parts = await loadAll(tx, tabId)
  const head = parts.head
  const state = reassemble(parts) as SuperTabState
  // A rule from before rules were per project names its project as commands do (projects.ts placeRules).
  placeRules(state)
  const account = await tx.routingPolicy.findUnique({ where: { id: stableId('routing-policy', state.ownerId, state.environment) } })
  const policy = effectivePolicy(account?.policy ?? null, state.routingPolicy ?? null).policy
  const projects = projectsOf(state)
  const documents: Plan['documents'] = []
  let alreadyDone = 0
  for (const project of projects) {
    if ((project.instructionsRevision ?? 0) > 0) { alreadyDone++; continue }
    const roleTexts = skillSetOf(project) === 'custom'
      ? Object.fromEntries((await tx.superTabRoleText.findMany({ where: { tabId, projectId: project.id } })).map(r => [r.roleId, r.text])) : {}
    const { from, text } = documentFor({ project, roleTexts, rules: projectRules(state, project.id), policy })
    documents.push({ tabId, projectId: project.id, from, bytes: Buffer.byteLength(text), text, project })
  }
  return { headVersion: head.version, head: head.data!, headFields: { groupCounter: parts.groupCounter, visibilityEpoch: parts.visibilityEpoch,
    sequenceBase: parts.sequenceBase }, projects, documents, alreadyDone }
}

/** Writes the documents and names their revision on the head, guarded by the head's version: a command in between wins,
 *  and the Swarm is failed and retried on the next run. */
async function writePlan(tx: Transaction, tabId: string, plan: Plan, now: number): Promise<void> {
  const written = new Map(plan.documents.map(d => [d.projectId, d]))
  // A Swarm from before projects keeps its one project only in `projectsOf`: it is written out, as any project command does.
  const projects = plan.projects.map(({ progress: _progress, ...project }) => {
    const document = written.get(project.id)
    return document ? { ...project, instructionsRevision: 1, instructionsHash: instructionsHash(document.text) } : project
  })
  await guardedWrite(tx, tabId, { op: 'update', kind: 'head', key: 'head', seen: plan.headVersion, data: { ...plan.head, projects }, head: plan.headFields }, clock.next())
  for (const document of plan.documents) {
    await writeInstructions(tx, tabId, { projectId: document.projectId, revision: 1, hash: instructionsHash(document.text), text: document.text,
      summary: MIGRATION_SUMMARY, writtenBy: { kind: 'system', id: 'migration' }, askedBy: document.project.ownerId, at: now })
  }
}

export async function migrateInstructions(db: PrismaClient, opts: { apply: boolean; now?: () => number }): Promise<InstructionsMigrationReport> {
  const now = opts.now ?? Date.now
  const report: InstructionsMigrationReport = { apply: opts.apply, swarms: 0, documents: [], alreadyDone: 0, skipped: [], failed: [] }
  const rows = await db.superTab.findMany({ select: { id: true, format: true }, orderBy: { id: 'asc' } })
  for (const row of rows) {
    if (row.format !== 2) { report.skipped.push(row.id); continue }
    report.swarms++
    try {
      const plan = opts.apply
        ? await swarmTransaction(db, async tx => {
          const planned = await planSwarm(tx, row.id)
          if (planned.documents.length) await writePlan(tx, row.id, planned, now())
          return planned
        }, TRANSACTION)
        : await planSwarm(db as unknown as Transaction, row.id)
      report.alreadyDone += plan.alreadyDone
      report.documents.push(...plan.documents.map(({ project: _project, ...document }) => document))
    } catch (error) {
      report.failed.push({ tabId: row.id, error: error instanceof Error ? error.message : String(error) })
    }
  }
  return report
}