Skip to content

Your team of AI agents, on your Mac, Windows or Linux. Agents that talk in channels, write code, review each other and use your tools, on the Claude Code, Codex, OpenCode or Pi you already have. Anything that touches the real world waits for your yes.

13.2 KB
Raw Blame
// A team as a Markdown file (spec §21): the agents, skills, channels and
// routines, readable by a person and importable on another Mac. No credentials,
// no memories, no conversations; grants and triggers point at connectors by
// name, and imported routines come in turned off.
import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs'
import { randomUUID } from 'node:crypto'
import { join } from 'node:path'
import { L, locale } from '../shared/lang'
import { overlongSkillNote } from '../shared/skills'
import { describeSchedule, MAX_AGENT_ROUTINES, modelInfo, type Agent, type AgentColor, type Effort, type GrantLevel, type Routine, type Schedule, type Trigger } from '../shared/types'
import { cleanLook } from './agent-look'
import type { Db } from './db'

const FENCE = 'tucano-team'
const OLD_FENCE = 'agent-desk-team' // teams exported before the rename
const KEEP_BACKUPS = 7
const DAY = 86_400_000

interface TeamFile {
  version: 1
  agents: {
    handle: string
    name: string
    role: string
    color: AgentColor
    customColor?: string
    avatar?: Agent['avatar'] // the drawn one; a picture stays on its computer
    instructions: string
    model: string
    effort: Effort
    limit: number
    web: boolean
    computer: boolean
    grants: Record<string, GrantLevel> // by connector name
  }[]
  skills: { name: string; description: string; body: string; agents: string[] }[] // agents by handle
  channels: { name: string; topic?: string; members: string[] }[]
  routines: { name: string; agent: string; where: string; prompt: string; schedule: Schedule; trigger?: { kind: 'poll'; connector: string; tool: string; args: Record<string, unknown>; everyMinutes: number } | { kind: 'webhook' } }[]
}

// `by`: who exports (the owner when left out). A routine in a DM goes only when the DM is theirs:
// no one takes another person's DM along (with one person, as always, every routine goes).
export function exportTeam(db: Db, by = db.ownerId()): string {
  const agents = db.agents().filter((a) => !a.archived && a.kind !== 'tuca') // each install has its own Tuca
  const handle = (id: string): string | undefined => agents.find((a) => a.id === id)?.handle
  const connectors = db.connectors()
  const connectorName = (id: string): string | undefined => connectors.find((c) => c.id === id)?.name
  const channels = db.conversations().filter((c) => c.kind === 'channel')
  const where = (convId: string): string => {
    const c = db.conversation(convId)
    return c?.kind === 'channel' ? `#${c.name}` : 'dm'
  }

  const data: TeamFile = {
    version: 1,
    agents: agents.map((a) => ({
      handle: a.handle,
      name: a.name,
      role: a.role,
      color: a.color,
      ...(a.customColor ? { customColor: a.customColor } : {}),
      ...(a.avatar ? { avatar: a.avatar } : {}),
      instructions: a.instructions,
      model: a.modelId,
      effort: a.effort,
      limit: a.limit,
      web: a.web !== false,
      computer: a.computer,
      grants: Object.fromEntries(Object.entries(a.grants).flatMap(([id, g]) => (g !== 'none' && connectorName(id) ? [[connectorName(id)!, g]] : [])))
    })),
    skills: db.skills().filter((k) => k.state === 'active').map((k) => ({ name: k.name, description: k.description, body: k.body, agents: k.agents.flatMap((id) => handle(id) ?? []) })),
    channels: channels.map((c) => ({ name: c.name, topic: c.topic, members: c.members.flatMap((id) => handle(id) ?? []) })),
    routines: db.routines().flatMap((r) => {
      const agent = handle(r.agentId)
      const c = db.conversationOwner(r.conversationId)
      if (!agent || !c || (c.kind === 'dm' && (c.owner ?? db.ownerId()) !== by)) return []
      const t = r.trigger
      const trigger = t?.kind === 'poll' ? (connectorName(t.connectorId) ? { kind: 'poll' as const, connector: connectorName(t.connectorId)!, tool: t.tool, args: t.args, everyMinutes: t.everyMinutes } : undefined) : t ? { kind: 'webhook' as const } : undefined
      return [{ name: r.name, agent, where: where(r.conversationId), prompt: r.prompt, schedule: r.schedule, ...(trigger ? { trigger } : {}) }]
    })
  }

  const md = [
    L('# Time do Tucano', '# Tucano team'),
    '',
    L(
      `Exportado em ${new Date().toLocaleString(locale())}. Sem credenciais, memórias nem conversas. Pra usar em outro computador: Configurações → Time → Importar.`,
      `Exported on ${new Date().toLocaleString(locale())}. No credentials, memories or conversations. To use it on another computer: Settings → Team → Import.`
    ),
    '',
    L('## Agentes', '## Agents'),
    ...data.agents.map(
      (a) =>
        `- **${a.name}** (@${a.handle})${a.role ? ` · ${a.role}` : ''} · ${modelInfo(a.model)?.label ?? a.model}${a.computer ? L(' · com computador', ' · with a computer') : ''}${Object.keys(a.grants).length ? ` · ${L('acessa', 'uses')} ${Object.keys(a.grants).join(', ')}` : ''}`
    ),
    '',
    ...(data.skills.length ? ['## Skills', ...data.skills.map((k) => `- **${k.name}**: ${k.description}`), ''] : []),
    ...(data.channels.length ? [L('## Canais', '## Channels'), ...data.channels.map((c) => `- #${c.name}: ${c.members.map((h) => `@${h}`).join(', ') || L('sem agentes', 'no agents')}`), ''] : []),
    ...(data.routines.length
      ? [
          L('## Rotinas', '## Routines'),
          ...data.routines.map(
            (r) =>
              `- **${r.name}** (@${r.agent}, ${r.where === 'dm' ? L('na DM', 'in the DM') : r.where}): ${r.trigger ? (r.trigger.kind === 'poll' ? L(`quando aparece algo novo em ${r.trigger.connector} · ${r.trigger.tool}`, `when something new shows up in ${r.trigger.connector} · ${r.trigger.tool}`) : L('quando chamada neste computador', 'when called on this computer')) : describeSchedule(r.schedule)}`
          ),
          ''
        ]
      : []),
    L('<!-- O bloco abaixo é o que o app importa. -->', '<!-- The block below is what the app imports. -->'),
    `\`\`\`json ${FENCE}`,
    JSON.stringify(data, null, 2),
    '```',
    ''
  ]
  return md.join('\n')
}

// Adds what isn't there yet (agents by handle, skills and channels by name).
// Routines come in off; a grant or trigger whose connector doesn't exist here is left out.
// `by`: who imports (the owner when left out): a routine for a DM goes into their DM with that
// agent, never into someone else's; what comes in is theirs.
export function importTeam(db: Db, text: string, defaultLimit: number, by = db.ownerId()): string {
  const m = new RegExp('```json (?:' + FENCE + '|' + OLD_FENCE + ')\\n([\\s\\S]*?)\\n```').exec(text)
  if (!m) throw new Error(L('Esse arquivo não é um time exportado pelo Tucano.', "That file isn't a team exported by Tucano."))
  let data: TeamFile
  try {
    data = JSON.parse(m[1]!) as TeamFile
  } catch {
    throw new Error(L('O bloco do time está corrompido.', "The team's block is corrupted."))
  }
  if (data.version !== 1) throw new Error(L('Versão de time desconhecida.', 'Unknown team version.'))
  const connectors = db.connectors()
  const connectorId = (name: string): string | undefined => connectors.find((c) => c.name === name)?.id
  const added = { agents: 0, skills: 0, channels: 0, routines: 0, skipped: [] as string[] }
  const longSkills: string[] = []

  for (const a of data.agents ?? []) {
    if (db.agents().some((x) => x.handle === a.handle)) continue
    const agent: Agent = {
      id: randomUUID(),
      name: a.name,
      handle: a.handle,
      role: a.role ?? '',
      color: a.color ?? 'sky',
      customColor: a.customColor,
      avatar: a.avatar,
      instructions: a.instructions ?? '',
      modelId: modelInfo(a.model)?.id ? a.model : 'sonnet',
      effort: a.effort ?? 'medium',
      maxRoutines: MAX_AGENT_ROUTINES,
      limit: a.limit || defaultLimit,
      used: 0,
      grants: Object.fromEntries(Object.entries(a.grants ?? {}).flatMap(([name, g]) => (connectorId(name) ? [[connectorId(name)!, g]] : (added.skipped.push(L(`acesso de @${a.handle} ao ${name}`, `@${a.handle}'s access to ${name}`)), [])))),
      memory: 'auto',
      computer: false, // turned on by hand: it downloads a system
      web: a.web,
      archived: false
    }
    db.saveAgent(cleanLook(agent))
    added.agents++
  }
  const byHandle = (h: string): string | undefined => db.agents().find((x) => x.handle === h)?.id

  for (const k of data.skills ?? []) {
    if (db.skills().some((x) => x.state === 'active' && x.name === k.name)) continue
    const note = overlongSkillNote(k.name, k.body.length)
    if (note) longSkills.push(note)
    const at = Date.now()
    db.saveSkill({ id: randomUUID(), name: k.name, description: k.description, body: k.body, agents: k.agents.flatMap((h) => byHandle(h) ?? []), state: 'active', createdAt: at, updatedAt: at })
    added.skills++
  }

  for (const c of data.channels ?? []) {
    const existing = db.conversations().find((x) => x.kind === 'channel' && x.name === c.name)
    const members = c.members.flatMap((h) => byHandle(h) ?? [])
    if (existing) {
      for (const id of members) if (!existing.members.includes(id)) db.setAgentChannels(id, [...db.conversations().filter((x) => x.kind === 'channel' && x.members.includes(id)).map((x) => x.id), existing.id])
      continue
    }
    db.createConversation({ id: randomUUID(), kind: 'channel', name: c.name, topic: c.topic, members, createdBy: by })
    added.channels++
  }

  for (const r of data.routines ?? []) {
    const agentId = byHandle(r.agent)
    const mine = (id: string): boolean => {
      const c = db.conversationOwner(id)
      return !!c && (c.kind !== 'dm' || (c.owner ?? db.ownerId()) === by)
    }
    if (!agentId || db.routines().some((x) => x.name === r.name && x.agentId === agentId && mine(x.conversationId))) continue
    let conversationId: string | undefined
    if (r.where === 'dm') {
      conversationId = db.conversations().find((c) => c.kind === 'dm' && c.name === agentId && (c.owner ?? db.ownerId()) === by)?.id
      if (!conversationId) {
        conversationId = randomUUID()
        db.createConversation({ id: conversationId, kind: 'dm', name: agentId, members: [agentId], owner: by })
      }
    } else conversationId = db.conversations().find((c) => c.kind === 'channel' && `#${c.name}` === r.where)?.id
    let trigger: Trigger | undefined
    if (r.trigger?.kind === 'poll') {
      const id = connectorId(r.trigger.connector)
      if (!id) {
        added.skipped.push(L(`a rotina "${r.name}" (precisa do conector ${r.trigger.connector})`, `the routine "${r.name}" (needs the ${r.trigger.connector} connector)`))
        continue
      }
      trigger = { kind: 'poll', connectorId: id, tool: r.trigger.tool, args: r.trigger.args, everyMinutes: r.trigger.everyMinutes }
    } else if (r.trigger?.kind === 'webhook') trigger = { kind: 'webhook', token: randomUUID().replace(/-/g, '') }
    if (!conversationId) continue
    const routine: Routine = { id: randomUUID(), name: r.name, agentId, conversationId, prompt: r.prompt, schedule: r.schedule, trigger, enabled: false, createdAt: Date.now(), owner: by }
    db.saveRoutine(routine)
    added.routines++
  }

  const parts = [
    added.agents && L(`${added.agents} agente${added.agents > 1 ? 's' : ''}`, `${added.agents} agent${added.agents > 1 ? 's' : ''}`),
    added.skills && `${added.skills} skill${added.skills > 1 ? 's' : ''}`,
    added.channels && L(`${added.channels} canal${added.channels > 1 ? 'is' : ''}`, `${added.channels} channel${added.channels > 1 ? 's' : ''}`),
    added.routines && L(`${added.routines} rotina${added.routines > 1 ? 's' : ''} (desligadas)`, `${added.routines} routine${added.routines > 1 ? 's' : ''} (off)`)
  ].filter(Boolean)
  const done = parts.length ? L(`Importei ${parts.join(', ')}.`, `Imported ${parts.join(', ')}.`) : L('Nada novo: tudo já existia aqui.', 'Nothing new: everything already existed here.')
  const long = longSkills.length ? L(` Skills longas: ${longSkills.join('; ')}.`, ` Long skills: ${longSkills.join('; ')}.`) : ''
  return `${done}${added.skipped.length ? L(` Ficou de fora: ${added.skipped.join('; ')}.`, ` Left out: ${added.skipped.join('; ')}.`) : ''}${long}`
}

// ---------- backups ----------

// A copy of the database (secrets stay encrypted for this Mac's keychain), named by
// when and then which workspace: names sort by date, so the oldest go first.
export function backup(db: Db, dir: string, workspaceName?: string): string {
  mkdirSync(dir, { recursive: true })
  const safe = (workspaceName ?? '')
    .normalize('NFD')
    .replace(/[\u0300-\u036f]/g, '')
    .replace(/[^a-z0-9]+/gi, '-')
    .replace(/^-+|-+$/g, '')
    .slice(0, 40)
  const file = join(dir, `tucano-${new Date().toISOString().slice(0, 16).replace(/[:T]/g, '-')}${safe ? `-${safe}` : ''}.db`)
  if (existsSync(file)) rmSync(file)
  db.backupTo(file)
  const old = readdirSync(dir)
    .filter((f) => /^(tucano|agent-desk)-.*\.db$/.test(f)) // and the ones from before the rename
    .sort()
    .slice(0, -KEEP_BACKUPS)
  for (const f of old) rmSync(join(dir, f), { force: true })
  return file
}

// Once a day, at startup or while the app stays open.
export function backupIfDue(db: Db, dir: string, workspaceName?: string): void {
  const last = existsSync(dir)
    ? readdirSync(dir)
        .filter((f) => f.endsWith('.db'))
        .map((f) => statSync(join(dir, f)).mtimeMs)
        .sort()
        .at(-1)
    : undefined
  if (!last || Date.now() - last > DAY) backup(db, dir, workspaceName)
}