@swarmclawai/swarmclaw 1.5.48 → 1.5.49

package/src/components/layout/sidebar-rail.tsx

@@ -282,6 +282,14 @@ export function SidebarRail({
               </svg>
             </NavItem>
 
+            <NavItem view="missions" label="Missions" expanded={railExpanded} isActive={isNavActive('missions')} onClick={() => handleNavClick('missions')}>
+              <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+                <circle cx="12" cy="12" r="10" />
+                <circle cx="12" cy="12" r="6" />
+                <circle cx="12" cy="12" r="2" />
+              </svg>
+            </NavItem>
+
             <NavItem view="schedules" label="Schedules" expanded={railExpanded} isActive={isNavActive('schedules')} onClick={() => handleNavClick('schedules')}>
               <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
                 <circle cx="12" cy="12" r="10" /><polyline points="12 6 12 12 16 14" />

package/src/lib/app/navigation.ts

@@ -15,6 +15,7 @@ const VIEW_TO_PATH: Record<AppView, string> = {
   memory: '/memory',
 
   tasks: '/tasks',
+  missions: '/missions',
   secrets: '/secrets',
   wallets: '/wallets',
   providers: '/providers',

package/src/lib/app/view-constants.ts

@@ -11,6 +11,7 @@ export const VIEW_LABELS: Record<AppView, string> = {
   memory: 'Memory',
 
   tasks: 'Tasks',
+  missions: 'Missions',
   secrets: 'Secrets',
   wallets: 'Wallets',
   providers: 'Providers',
@@ -35,6 +36,7 @@ export const CREATE_LABELS: Partial<Record<AppView, string>> = {
   agents: 'Agent',
   schedules: 'Schedule',
   tasks: 'Task',
+  missions: 'Mission',
   secrets: 'Secret',
   providers: 'Provider',
   skills: 'Skill',
@@ -57,6 +59,7 @@ export const VIEW_DESCRIPTIONS: Record<AppView, string> = {
   memory: 'Long-term agent memory store',
 
   tasks: 'Task board for agent work and queued runs',
+  missions: 'Autonomous goal-driven agent runs with budgets and morning reports',
   secrets: 'API keys, tokens, and encrypted credentials',
   wallets: 'Crypto wallets for agent-initiated on-chain transactions',
   providers: 'LLM providers & custom endpoints',
@@ -115,6 +118,12 @@ export const VIEW_EMPTY_STATES: Record<Exclude<AppView, 'agents' | 'home'>, { ic
     description: 'A kanban board for managing agent work. Create tasks, assign them to agents, and track progress.',
     features: ['Kanban columns: Backlog, Queued, Running, Completed, Failed', 'Assign tasks to specific agents', 'Track retries, results, and logs', 'Review status without leaving the board'],
   },
+  missions: {
+    icon: 'target',
+    title: 'Missions',
+    description: 'Hand your agent team a goal and let them run overnight. Budgets, periodic reports, and a full timeline you can review in the morning.',
+    features: ['Set USD, token, turn, and wallclock caps enforced at the session level', 'Periodic markdown reports delivered as in-app notifications', 'Full milestone timeline with evidence and end reasons', 'Start, pause, resume, and cancel from the dashboard or CLI'],
+  },
   secrets: {
     icon: 'lock',
     title: 'Secrets',
@@ -234,5 +243,5 @@ export const VIEW_EMPTY_STATES: Record<Exclude<AppView, 'agents' | 'home'>, { ic
 export const FULL_WIDTH_VIEWS = new Set<AppView>([
   'home', 'org_chart', 'inbox', 'chatrooms', 'protocols', 'schedules', 'secrets', 'wallets', 'providers', 'skills',
   'connectors', 'webhooks', 'mcp_servers', 'knowledge', 'extensions',
-  'usage', 'runs', 'autonomy', 'logs', 'settings', 'activity', 'projects', 'swarmfeed', 'marketplace',
+  'usage', 'runs', 'autonomy', 'logs', 'settings', 'activity', 'projects', 'swarmfeed', 'marketplace', 'missions',
 ])

package/src/lib/server/missions/mission-budget-hook.ts

@@ -0,0 +1,38 @@
+import { log } from '@/lib/server/logger'
+import { evaluateMissionBudget, markBudgetExhausted } from './mission-service'
+import { getMission } from './mission-repository'
+
+const TAG = 'mission-budget'
+
+export interface MissionBudgetHookResult {
+  allow: boolean
+  reason?: string
+}
+
+/**
+ * Pure, synchronous check suitable for the hot enqueue path. When the hook
+ * denies a run it also fires a side-effect to transition the mission to
+ * budget_exhausted — callers should throw on `allow: false` to surface the
+ * block to the caller (heartbeat loops back off on thrown errors).
+ */
+export function checkMissionBudgetForSession(missionId: string | null | undefined): MissionBudgetHookResult {
+  if (!missionId) return { allow: true }
+  const mission = getMission(missionId)
+  if (!mission) return { allow: true }
+  if (mission.status !== 'running') {
+    if (mission.status === 'paused' || mission.status === 'draft') {
+      return { allow: false, reason: `Mission ${mission.id} is ${mission.status}` }
+    }
+    return { allow: false, reason: `Mission ${mission.id} is ${mission.status}` }
+  }
+  const verdict = evaluateMissionBudget(mission)
+  if (!verdict.allow) {
+    try {
+      markBudgetExhausted(mission.id, verdict.reason ?? 'Budget exhausted')
+    } catch (error) {
+      log.warn(TAG, `Failed to transition mission ${mission.id} to budget_exhausted`, error)
+    }
+    return { allow: false, reason: verdict.reason }
+  }
+  return { allow: true }
+}

package/src/lib/server/missions/mission-report-builder.test.ts

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { after, before, describe, it } from 'node:test'
+
+import type { Mission } from '@/types'
+
+const originalEnv = {
+  DATA_DIR: process.env.DATA_DIR,
+  WORKSPACE_DIR: process.env.WORKSPACE_DIR,
+  SWARMCLAW_BUILD_MODE: process.env.SWARMCLAW_BUILD_MODE,
+}
+
+let tempDir = ''
+let builder: typeof import('./mission-report-builder')
+let service: typeof import('./mission-service')
+let repo: typeof import('./mission-repository')
+
+before(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-report-builder-'))
+  process.env.DATA_DIR = path.join(tempDir, 'data')
+  process.env.WORKSPACE_DIR = path.join(tempDir, 'workspace')
+  process.env.SWARMCLAW_BUILD_MODE = '1'
+  builder = await import('./mission-report-builder')
+  service = await import('./mission-service')
+  repo = await import('./mission-repository')
+})
+
+after(() => {
+  if (originalEnv.DATA_DIR === undefined) delete process.env.DATA_DIR
+  else process.env.DATA_DIR = originalEnv.DATA_DIR
+  if (originalEnv.WORKSPACE_DIR === undefined) delete process.env.WORKSPACE_DIR
+  else process.env.WORKSPACE_DIR = originalEnv.WORKSPACE_DIR
+  if (originalEnv.SWARMCLAW_BUILD_MODE === undefined) delete process.env.SWARMCLAW_BUILD_MODE
+  else process.env.SWARMCLAW_BUILD_MODE = originalEnv.SWARMCLAW_BUILD_MODE
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+function makeRunningMission(label: string): Mission {
+  const m = service.createMission({
+    title: `Test report mission ${label}`,
+    goal: 'Write haikus',
+    successCriteria: ['3 haikus saved', 'Each 5-7-5'],
+    rootSessionId: `rep_s_${label}`,
+    agentIds: ['a1'],
+    budget: { maxUsd: 0.5, maxTokens: 5000, maxTurns: 10, maxWallclockSec: 600 },
+  })
+  const started = service.startMission(m.id)
+  return started ?? m
+}
+
+describe('mission-report-builder', () => {
+  it('builds a markdown progress report with usage and milestones', () => {
+    const m = makeRunningMission('rep_1')
+    service.recordTurnUsage(m.id, { turnsDelta: 2, tokensDelta: 500, usdDelta: 0.05 })
+    repo.appendMissionMilestone(m.id, { kind: 'subgoal_done', summary: 'Haiku one drafted' })
+    const latest = repo.getMission(m.id)!
+    const { report, deliveryTitle, deliveryMessage } = builder.buildMissionReport(latest, {
+      from: latest.createdAt,
+      to: Date.now(),
+    })
+    assert.ok(report.body.includes('# Test report mission rep_1: progress update'))
+    assert.ok(report.body.includes('**Goal**: Write haikus'))
+    assert.ok(report.body.includes('Turns run: 2 / 10'))
+    assert.ok(report.body.includes('Tokens used: 500 / 5000'))
+    assert.ok(report.body.includes('Spend: $0.05 / $0.50'))
+    assert.ok(report.body.includes('3 haikus saved'))
+    assert.ok(report.body.includes('Milestones'))
+    assert.ok(report.body.includes('Haiku one drafted'))
+    assert.equal(report.format, 'markdown')
+    assert.equal(report.missionId, m.id)
+    assert.ok(deliveryTitle.includes('Test report mission'))
+    assert.ok(deliveryMessage.includes('still running'))
+  })
+
+  it('builds a final report when isFinal is set, including end reason', () => {
+    const m = makeRunningMission('rep_2')
+    service.cancelMission(m.id, 'user aborted')
+    const cancelled = repo.getMission(m.id)!
+    const { report, deliveryMessage } = builder.buildMissionReport(cancelled, {
+      from: cancelled.createdAt,
+      to: Date.now(),
+    }, { isFinal: true })
+    assert.ok(report.body.includes('final report'))
+    assert.ok(report.body.includes('## End reason'))
+    assert.ok(report.body.includes('user aborted'))
+    assert.ok(deliveryMessage.includes('has ended'))
+  })
+
+  it('includes up to the last N milestones when the list is long', () => {
+    const m = makeRunningMission('rep_3')
+    for (let i = 0; i < 25; i++) {
+      repo.appendMissionMilestone(m.id, { kind: 'check_in', summary: `check ${i}` })
+    }
+    const latest = repo.getMission(m.id)!
+    const { report } = builder.buildMissionReport(latest, {
+      from: 0,
+      to: Date.now(),
+    })
+    // Body should mention the last check (24), but capped at 20 listed
+    assert.ok(report.body.includes('check 24'))
+    const milestoneLines = report.body.split('\n').filter((l) => l.includes('**check_in**'))
+    assert.ok(milestoneLines.length <= 20)
+  })
+})

package/src/lib/server/missions/mission-report-builder.ts

@@ -0,0 +1,158 @@
+import crypto from 'crypto'
+import type { Mission, MissionEvent, MissionReport } from '@/types'
+import { getRecentMessages } from '@/lib/server/messages/message-repository'
+import { listMissionEvents } from './mission-repository'
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const sec = Math.round(ms / 1000)
+  if (sec < 60) return `${sec}s`
+  const min = Math.round(sec / 60)
+  if (min < 60) return `${min}m`
+  const hr = Math.round(min / 60 * 10) / 10
+  return `${hr}h`
+}
+
+function formatUsd(n: number): string {
+  return `$${n.toFixed(n < 0.01 ? 4 : 2)}`
+}
+
+function formatWhen(at: number): string {
+  try {
+    return new Date(at).toISOString().replace('T', ' ').slice(0, 19) + ' UTC'
+  } catch {
+    return String(at)
+  }
+}
+
+export interface MissionReportOptions {
+  isFinal?: boolean
+  windowSource?: 'schedule' | 'final' | 'on_demand'
+}
+
+export interface BuiltMissionReport {
+  report: MissionReport
+  deliveryMessage: string
+  deliveryTitle: string
+}
+
+function extractHighlights(events: MissionEvent[]): MissionReport['highlights'] {
+  const milestones = events.filter((e) => e.kind.startsWith('milestone:'))
+  return milestones.slice(-5).map((ev) => ({
+    kind: ev.kind,
+    summary: typeof ev.payload.summary === 'string' ? ev.payload.summary : ev.kind,
+    evidenceRunId: ev.runId ?? null,
+  }))
+}
+
+function collectRecentTranscriptLines(missionRootSessionId: string, window: { from: number; to: number }): string[] {
+  try {
+    const messages = getRecentMessages(missionRootSessionId, 40)
+    return messages
+      .filter((m) => {
+        const ts = typeof m.time === 'number' ? m.time : 0
+        return ts >= window.from && ts <= window.to
+      })
+      .slice(-20)
+      .map((m) => {
+        const role = m.role || 'system'
+        const text = (typeof m.text === 'string' ? m.text : '').split('\n')[0].slice(0, 280)
+        return `- **${role}**: ${text}`
+      })
+  } catch {
+    return []
+  }
+}
+
+export function renderMissionReportMarkdown(
+  mission: Mission,
+  events: MissionEvent[],
+  transcriptLines: string[],
+  window: { from: number; to: number },
+  opts: MissionReportOptions,
+): { title: string; body: string } {
+  const title = opts.isFinal
+    ? `${mission.title}: final report`
+    : `${mission.title}: progress update`
+
+  const parts: string[] = []
+  parts.push(`# ${title}`)
+  parts.push('')
+  parts.push(`**Goal**: ${mission.goal}`)
+  parts.push('')
+  parts.push(`**Status**: \`${mission.status}\``)
+  parts.push('')
+  parts.push(`**Window**: ${formatWhen(window.from)} to ${formatWhen(window.to)}`)
+  parts.push('')
+
+  parts.push('## Usage')
+  parts.push(`- Turns run: ${mission.usage.turnsRun}${mission.budget.maxTurns != null ? ` / ${mission.budget.maxTurns}` : ''}`)
+  parts.push(`- Tokens used: ${mission.usage.tokensUsed}${mission.budget.maxTokens != null ? ` / ${mission.budget.maxTokens}` : ''}`)
+  parts.push(`- Spend: ${formatUsd(mission.usage.usdSpent)}${mission.budget.maxUsd != null ? ` / ${formatUsd(mission.budget.maxUsd)}` : ''}`)
+  parts.push(`- Wallclock: ${formatDuration(mission.usage.wallclockMsElapsed)}${mission.budget.maxWallclockSec != null ? ` / ${formatDuration(mission.budget.maxWallclockSec * 1000)}` : ''}`)
+  parts.push('')
+
+  if (mission.successCriteria.length > 0) {
+    parts.push('## Success criteria')
+    for (const c of mission.successCriteria) parts.push(`- ${c}`)
+    parts.push('')
+  }
+
+  const milestones = events.filter((e) => e.kind.startsWith('milestone:'))
+  if (milestones.length > 0) {
+    parts.push(`## Milestones (${milestones.length})`)
+    for (const ev of milestones.slice(-20)) {
+      const kind = ev.kind.replace('milestone:', '')
+      const summary = typeof ev.payload.summary === 'string' ? ev.payload.summary : kind
+      parts.push(`- **${kind}** at ${formatWhen(ev.at)}: ${summary}`)
+    }
+    parts.push('')
+  }
+
+  if (transcriptLines.length > 0) {
+    parts.push('## Recent activity')
+    for (const line of transcriptLines) parts.push(line)
+    parts.push('')
+  }
+
+  if (opts.isFinal && mission.endReason) {
+    parts.push('## End reason')
+    parts.push(mission.endReason)
+    parts.push('')
+  }
+
+  parts.push('---')
+  parts.push('_Generated by SwarmClaw Missions._')
+
+  return { title, body: parts.join('\n') }
+}
+
+export function buildMissionReport(
+  mission: Mission,
+  window: { from: number; to: number },
+  opts: MissionReportOptions = {},
+): BuiltMissionReport {
+  const events = listMissionEvents(mission.id, { sinceAt: window.from, untilAt: window.to })
+  const transcriptLines = collectRecentTranscriptLines(mission.rootSessionId, window)
+  const { title, body } = renderMissionReportMarkdown(mission, events, transcriptLines, window, opts)
+
+  const report: MissionReport = {
+    id: `mrep_${crypto.randomBytes(8).toString('hex')}`,
+    missionId: mission.id,
+    generatedAt: Date.now(),
+    format: 'markdown',
+    fromAt: window.from,
+    toAt: window.to,
+    title,
+    body,
+    audioUrl: null,
+    deliveredTo: [],
+    highlights: extractHighlights(events),
+  }
+
+  const deliveryMessage = opts.isFinal
+    ? `Mission "${mission.title}" has ended. Open SwarmClaw to review the final report.`
+    : `Mission "${mission.title}" is still running. ${mission.usage.turnsRun} turns done.`
+
+  return { report, deliveryMessage, deliveryTitle: title }
+}

package/src/lib/server/missions/mission-repository.test.ts

@@ -0,0 +1,171 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { after, before, describe, it } from 'node:test'
+
+import type { Mission } from '@/types'
+
+const originalEnv = {
+  DATA_DIR: process.env.DATA_DIR,
+  WORKSPACE_DIR: process.env.WORKSPACE_DIR,
+  SWARMCLAW_BUILD_MODE: process.env.SWARMCLAW_BUILD_MODE,
+}
+
+let tempDir = ''
+let repo: typeof import('./mission-repository')
+
+function makeMission(overrides: Partial<Mission> = {}): Mission {
+  const now = Date.now()
+  return {
+    id: overrides.id ?? 'mi_test_1',
+    title: 'Smoke mission',
+    goal: 'Write 3 haikus about budgets',
+    successCriteria: ['File haikus.md has 3 stanzas'],
+    rootSessionId: 's1',
+    agentIds: ['a1'],
+    status: 'draft',
+    budget: {
+      maxUsd: 0.1,
+      maxTokens: 5000,
+      maxToolCalls: null,
+      maxWallclockSec: 600,
+      maxTurns: 20,
+      warnAtFractions: [0.5, 0.8, 0.95],
+    },
+    usage: {
+      usdSpent: 0,
+      tokensUsed: 0,
+      toolCallsUsed: 0,
+      turnsRun: 0,
+      wallclockMsElapsed: 0,
+      startedAt: null,
+      lastUpdatedAt: now,
+      warnFractionsHit: [],
+    },
+    milestones: [],
+    reportSchedule: null,
+    reportConnectorIds: [],
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  }
+}
+
+before(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-missions-'))
+  process.env.DATA_DIR = path.join(tempDir, 'data')
+  process.env.WORKSPACE_DIR = path.join(tempDir, 'workspace')
+  process.env.SWARMCLAW_BUILD_MODE = '1'
+  repo = await import('./mission-repository')
+})
+
+after(() => {
+  if (originalEnv.DATA_DIR === undefined) delete process.env.DATA_DIR
+  else process.env.DATA_DIR = originalEnv.DATA_DIR
+  if (originalEnv.WORKSPACE_DIR === undefined) delete process.env.WORKSPACE_DIR
+  else process.env.WORKSPACE_DIR = originalEnv.WORKSPACE_DIR
+  if (originalEnv.SWARMCLAW_BUILD_MODE === undefined) delete process.env.SWARMCLAW_BUILD_MODE
+  else process.env.SWARMCLAW_BUILD_MODE = originalEnv.SWARMCLAW_BUILD_MODE
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+describe('mission-repository', () => {
+  it('persists and retrieves a mission', () => {
+    const mission = makeMission({ id: 'mi_persist_1' })
+    repo.upsertMission(mission)
+    const fetched = repo.getMission('mi_persist_1')
+    assert.ok(fetched)
+    assert.equal(fetched?.title, 'Smoke mission')
+    assert.equal(fetched?.status, 'draft')
+  })
+
+  it('lists missions newest-first', () => {
+    const older = makeMission({ id: 'mi_list_old', createdAt: 1_000 })
+    const newer = makeMission({ id: 'mi_list_new', createdAt: 2_000 })
+    repo.upsertMission(older)
+    repo.upsertMission(newer)
+    const all = repo.listMissions()
+    const olderIdx = all.findIndex((m) => m.id === 'mi_list_old')
+    const newerIdx = all.findIndex((m) => m.id === 'mi_list_new')
+    assert.ok(newerIdx >= 0 && olderIdx >= 0)
+    assert.ok(newerIdx < olderIdx, 'newer mission should appear before older')
+  })
+
+  it('patches a mission and bumps updatedAt', async () => {
+    const mission = makeMission({ id: 'mi_patch_1', updatedAt: 1_000 })
+    repo.upsertMission(mission)
+    await new Promise((resolve) => setTimeout(resolve, 5))
+    const patched = repo.patchMission('mi_patch_1', (m) => {
+      if (!m) return null
+      return { ...m, status: 'running' }
+    })
+    assert.ok(patched)
+    assert.equal(patched?.status, 'running')
+    assert.ok((patched?.updatedAt ?? 0) > 1_000)
+  })
+
+  it('appends milestones with cap and writes an event', () => {
+    const mission = makeMission({ id: 'mi_milestone_1' })
+    repo.upsertMission(mission)
+    repo.appendMissionMilestone('mi_milestone_1', {
+      kind: 'started',
+      summary: 'Mission started',
+    })
+    const fetched = repo.getMission('mi_milestone_1')
+    assert.equal(fetched?.milestones.length, 1)
+    assert.equal(fetched?.milestones[0].kind, 'started')
+    const events = repo.listMissionEvents('mi_milestone_1')
+    assert.ok(events.some((e) => e.kind === 'milestone:started'))
+  })
+
+  it('caps milestone tail at the configured maximum', () => {
+    const mission = makeMission({ id: 'mi_cap_1' })
+    repo.upsertMission(mission)
+    for (let i = 0; i < 205; i++) {
+      repo.appendMissionMilestone('mi_cap_1', {
+        kind: 'check_in',
+        summary: `check ${i}`,
+      })
+    }
+    const fetched = repo.getMission('mi_cap_1')
+    assert.equal(fetched?.milestones.length, 200)
+    // Oldest retained should be check 5 (first five were trimmed)
+    assert.equal(fetched?.milestones[0].summary, 'check 5')
+    assert.equal(fetched?.milestones[199].summary, 'check 204')
+  })
+
+  it('saves and lists reports newest-first', () => {
+    const mission = makeMission({ id: 'mi_report_1' })
+    repo.upsertMission(mission)
+    const now = Date.now()
+    repo.saveMissionReport({
+      id: 'mrep_1',
+      missionId: 'mi_report_1',
+      generatedAt: now - 1000,
+      format: 'markdown',
+      fromAt: now - 2000,
+      toAt: now - 1000,
+      title: 'First report',
+      body: 'body 1',
+      deliveredTo: [],
+      highlights: [],
+    })
+    repo.saveMissionReport({
+      id: 'mrep_2',
+      missionId: 'mi_report_1',
+      generatedAt: now,
+      format: 'markdown',
+      fromAt: now - 1000,
+      toAt: now,
+      title: 'Second report',
+      body: 'body 2',
+      deliveredTo: [],
+      highlights: [],
+    })
+    const reports = repo.listMissionReports('mi_report_1')
+    assert.equal(reports.length, 2)
+    assert.equal(reports[0].id, 'mrep_2')
+    assert.equal(reports[1].id, 'mrep_1')
+  })
+})

package/src/lib/server/missions/mission-repository.ts

@@ -0,0 +1,137 @@
+import crypto from 'crypto'
+import type {
+  Mission,
+  MissionEvent,
+  MissionMilestone,
+  MissionReport,
+} from '@/types'
+import { MISSION_MILESTONE_TAIL_CAP } from '@/types'
+import {
+  loadAgentMission,
+  loadAgentMissions,
+  upsertAgentMission,
+  patchAgentMission,
+  deleteAgentMission,
+  upsertAgentMissionEvent,
+  loadAgentMissionEvents,
+  upsertMissionReport,
+  loadMissionReports,
+  loadMissionReport,
+} from '@/lib/server/storage'
+
+function newId(prefix: string): string {
+  return `${prefix}_${crypto.randomBytes(8).toString('hex')}`
+}
+
+export function listMissions(): Mission[] {
+  const all = loadAgentMissions()
+  return Object.values(all).sort((a, b) => b.createdAt - a.createdAt)
+}
+
+export function getMission(id: string): Mission | null {
+  return loadAgentMission(id)
+}
+
+export function upsertMission(mission: Mission): void {
+  const withTimestamps: Mission = {
+    ...mission,
+    updatedAt: Date.now(),
+  }
+  upsertAgentMission(mission.id, withTimestamps)
+}
+
+export function patchMission(
+  id: string,
+  updater: (current: Mission | null) => Mission | null,
+): Mission | null {
+  return patchAgentMission(id, (current) => {
+    const next = updater(current)
+    if (!next) return next
+    return { ...next, updatedAt: Date.now() }
+  })
+}
+
+export function removeMission(id: string): void {
+  deleteAgentMission(id)
+}
+
+export function appendMissionEvent(
+  missionId: string,
+  kind: string,
+  payload: Record<string, unknown> = {},
+  opts: { sessionId?: string | null; runId?: string | null; at?: number } = {},
+): MissionEvent {
+  const event: MissionEvent = {
+    id: newId('mev'),
+    missionId,
+    at: opts.at ?? Date.now(),
+    kind,
+    payload,
+    sessionId: opts.sessionId ?? null,
+    runId: opts.runId ?? null,
+  }
+  upsertAgentMissionEvent(event.id, event)
+  return event
+}
+
+export function appendMissionMilestone(
+  missionId: string,
+  milestone: Omit<MissionMilestone, 'id' | 'at'> & { at?: number; id?: string },
+): Mission | null {
+  return patchMission(missionId, (current) => {
+    if (!current) return null
+    const entry: MissionMilestone = {
+      id: milestone.id ?? newId('ms'),
+      at: milestone.at ?? Date.now(),
+      kind: milestone.kind,
+      summary: milestone.summary.slice(0, 240),
+      evidence: milestone.evidence,
+      sessionId: milestone.sessionId ?? null,
+      runId: milestone.runId ?? null,
+    }
+    const next = [...current.milestones, entry]
+    const capped = next.length > MISSION_MILESTONE_TAIL_CAP
+      ? next.slice(-MISSION_MILESTONE_TAIL_CAP)
+      : next
+    // Also persist to the events table so the full history is never lost
+    appendMissionEvent(missionId, `milestone:${entry.kind}`, {
+      milestoneId: entry.id,
+      summary: entry.summary,
+      evidence: entry.evidence,
+    }, { sessionId: entry.sessionId, runId: entry.runId, at: entry.at })
+    return { ...current, milestones: capped }
+  })
+}
+
+export function listMissionEvents(missionId: string, opts: { sinceAt?: number; untilAt?: number } = {}): MissionEvent[] {
+  const all = loadAgentMissionEvents()
+  const sinceAt = opts.sinceAt ?? 0
+  const untilAt = opts.untilAt ?? Number.MAX_SAFE_INTEGER
+  return Object.values(all)
+    .filter((ev) => ev.missionId === missionId && ev.at >= sinceAt && ev.at <= untilAt)
+    .sort((a, b) => a.at - b.at)
+}
+
+export function saveMissionReport(report: MissionReport): void {
+  upsertMissionReport(report.id, report)
+  appendMissionEvent(report.missionId, 'report_generated', {
+    reportId: report.id,
+    format: report.format,
+    fromAt: report.fromAt,
+    toAt: report.toAt,
+  }, { at: report.generatedAt })
+}
+
+export function getMissionReport(id: string): MissionReport | null {
+  return loadMissionReport(id)
+}
+
+export function listMissionReports(missionId: string, limit = 20): MissionReport[] {
+  const all = loadMissionReports()
+  return Object.values(all)
+    .filter((r) => r.missionId === missionId)
+    .sort((a, b) => b.generatedAt - a.generatedAt)
+    .slice(0, limit)
+}
+
+export { newId as newMissionId }