@swarmclawai/swarmclaw 1.2.9 → 1.3.1

package/src/lib/server/usage/cost-rollup.ts

@@ -0,0 +1,124 @@
+import type { Agent } from '@/types'
+import { patchAgent } from '@/lib/server/agents/agent-repository'
+import { logActivity } from '@/lib/server/activity/activity-log'
+import { notify } from '@/lib/server/ws-hub'
+import { log } from '@/lib/server/logger'
+
+const TAG = 'cost-rollup'
+
+const ONE_HOUR_MS = 60 * 60 * 1000
+
+function toWindowBoundaries(now: number) {
+  const d = new Date(now)
+  const dayStart = new Date(d)
+  dayStart.setUTCHours(0, 0, 0, 0)
+  const monthStart = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1))
+  return {
+    hourStartTs: now - ONE_HOUR_MS,
+    dayStartTs: dayStart.getTime(),
+    monthStartTs: monthStart.getTime(),
+  }
+}
+
+/**
+ * Push-based cost rollup: atomically increments the agent's persisted spend
+ * fields and checks budgets. Called immediately after each usage record is appended.
+ */
+export function rollupCostToAgent(agentId: string, costUsd: number): void {
+  if (!agentId || !Number.isFinite(costUsd) || costUsd <= 0) return
+
+  const now = Date.now()
+  const costCents = Math.round(costUsd * 100)
+  const { hourStartTs, dayStartTs, monthStartTs } = toWindowBoundaries(now)
+
+  const updated = patchAgent(agentId, (current) => {
+    if (!current) return null
+    const lastRollup = current.lastSpendRollupAt ?? 0
+    const lastBounds = toWindowBoundaries(lastRollup)
+
+    // Reset windows that have rolled over since last rollup
+    let hourly = current.spentHourlyCents ?? 0
+    let daily = current.spentDailyCents ?? 0
+    let monthly = current.spentMonthlyCents ?? 0
+
+    if (lastRollup < hourStartTs) hourly = 0
+    if (lastBounds.dayStartTs < dayStartTs) daily = 0
+    if (lastBounds.monthStartTs < monthStartTs) monthly = 0
+
+    return {
+      ...current,
+      spentHourlyCents: hourly + costCents,
+      spentDailyCents: daily + costCents,
+      spentMonthlyCents: monthly + costCents,
+      lastSpendRollupAt: now,
+    }
+  })
+
+  if (!updated) return
+
+  // Check budgets and enforce
+  checkAndEnforceBudget(updated)
+}
+
+/**
+ * Checks agent's persisted spend against configured budgets and logs
+ * activity entries when thresholds are hit.
+ */
+function checkAndEnforceBudget(agent: Agent): void {
+  const WARNING_RATIO = 0.8
+
+  const windows = [
+    { key: 'hourly' as const, budget: agent.hourlyBudget, spent: (agent.spentHourlyCents ?? 0) / 100 },
+    { key: 'daily' as const, budget: agent.dailyBudget, spent: (agent.spentDailyCents ?? 0) / 100 },
+    { key: 'monthly' as const, budget: agent.monthlyBudget, spent: (agent.spentMonthlyCents ?? 0) / 100 },
+  ]
+
+  for (const { key, budget, spent } of windows) {
+    if (!budget || !Number.isFinite(budget) || budget <= 0) continue
+    const ratio = spent / budget
+
+    if (ratio >= 1) {
+      log.warn(TAG, `Agent "${agent.name}" exceeded ${key} budget: $${spent.toFixed(4)} / $${budget.toFixed(2)}`)
+      logActivity({
+        entityType: 'budget',
+        entityId: agent.id,
+        action: 'budget_exceeded',
+        actor: 'system',
+        summary: `Agent "${agent.name}" exceeded ${key} budget: $${spent.toFixed(4)} / $${budget.toFixed(2)}`,
+        detail: { window: key, spent, budget, ratio },
+      })
+      notify('agents')
+    } else if (ratio >= WARNING_RATIO) {
+      logActivity({
+        entityType: 'budget',
+        entityId: agent.id,
+        action: 'budget_warning',
+        actor: 'system',
+        summary: `Agent "${agent.name}" nearing ${key} budget: $${spent.toFixed(4)} / $${budget.toFixed(2)} (${Math.round(ratio * 100)}%)`,
+        detail: { window: key, spent, budget, ratio },
+      })
+    }
+  }
+}
+
+/**
+ * Reset all agents' daily spend counters. Call at UTC midnight.
+ */
+export function resetDailySpends(agents: Record<string, Agent>): void {
+  for (const agent of Object.values(agents)) {
+    if ((agent.spentDailyCents ?? 0) > 0) {
+      patchAgent(agent.id, (current) => current ? { ...current, spentDailyCents: 0 } : null)
+    }
+  }
+}
+
+/**
+ * Reset all agents' monthly spend counters. Call at UTC month boundary.
+ */
+export function resetMonthlySpends(agents: Record<string, Agent>): void {
+  for (const agent of Object.values(agents)) {
+    if ((agent.spentMonthlyCents ?? 0) > 0) {
+      patchAgent(agent.id, (current) => current ? { ...current, spentMonthlyCents: 0 } : null)
+    }
+  }
+}

package/src/lib/server/usage/usage-repository.ts

@@ -8,6 +8,7 @@ import {
   saveUsage as saveStoredUsage,
 } from '@/lib/server/storage'
 import { perf } from '@/lib/server/runtime/perf'
+import { rollupCostToAgent } from './cost-rollup'
 
 export function loadUsage(): Record<string, UsageRecord[]> {
   return perf.measureSync('repository', 'usage.list', () => loadStoredUsage())
@@ -19,6 +20,11 @@ export function saveUsage(data: Record<string, UsageRecord[]>): void {
 
 export function appendUsage(sessionId: string, record: unknown): void {
   perf.measureSync('repository', 'usage.append', () => appendStoredUsage(sessionId, record), { sessionId })
+  // Push-based cost rollup: update persisted spend fields and check budgets
+  const rec = record as Partial<UsageRecord>
+  if (rec.agentId && typeof rec.estimatedCost === 'number' && rec.estimatedCost > 0) {
+    rollupCostToAgent(rec.agentId, rec.estimatedCost)
+  }
 }
 
 export function getUsageSpendSince(minTimestamp: number): number {

package/src/lib/validation/schemas.ts

@@ -1,6 +1,4 @@
 import { z } from 'zod'
-import type { ProtocolStepDefinition } from '@/types'
-import { validateStepDag, validateStepRefs } from '@/lib/server/protocols/step-dag-validation'
 
 const OllamaModeSchema = z.enum(['local', 'cloud']).nullable().optional().default(null)
 
@@ -424,7 +422,9 @@ export const ProtocolRunCreateSchema = z.object({
   entryStepId: z.string().nullable().optional().default(null),
 })
 
-export const ProtocolTemplateUpsertSchema = z.object({
+/** Base protocol template schema without server-side DAG validation.
+ *  Use ProtocolTemplateUpsertSchema from '@/lib/validation/server-schemas' for full server-side validation. */
+export const ProtocolTemplateUpsertBaseSchema = z.object({
   name: z.string().min(1, 'A template name is required'),
   description: z.string().min(1, 'A template description is required'),
   singleAgentAllowed: z.boolean().optional().default(true),
@@ -433,33 +433,6 @@ export const ProtocolTemplateUpsertSchema = z.object({
   defaultPhases: z.array(ProtocolPhaseDefinitionSchema).optional().default([]),
   steps: z.array(ProtocolStepDefinitionSchema).optional().default([]),
   entryStepId: z.string().nullable().optional().default(null),
-}).superRefine((value, ctx) => {
-  if (value.defaultPhases.length === 0 && value.steps.length === 0) {
-    ctx.addIssue({
-      code: z.ZodIssueCode.custom,
-      path: ['steps'],
-      message: 'Provide at least one phase or one step.',
-    })
-  }
-  if (value.steps.length > 0) {
-    const steps = value.steps as ProtocolStepDefinition[]
-    const dagResult = validateStepDag(steps)
-    if (!dagResult.valid) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ['steps'],
-        message: `Cycle detected in step dependencies: ${dagResult.cycle?.join(' → ')}`,
-      })
-    }
-    const invalidRefs = validateStepRefs(steps)
-    for (const ref of invalidRefs) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ['steps'],
-        message: `Step references unknown step ID: "${ref}"`,
-      })
-    }
-  }
 })
 
 export const ProtocolRunActionSchema = z.object({

package/src/lib/validation/server-schemas.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import type { ProtocolStepDefinition } from '@/types'
+import { validateStepDag, validateStepRefs } from '@/lib/server/protocols/step-dag-validation'
+import { ProtocolTemplateUpsertBaseSchema } from './schemas'
+
+/** Full protocol template upsert schema with server-side DAG validation.
+ *  For client-side use (without server deps), use ProtocolTemplateUpsertBaseSchema from './schemas'. */
+export const ProtocolTemplateUpsertSchema = ProtocolTemplateUpsertBaseSchema.superRefine((value, ctx) => {
+  if (value.defaultPhases.length === 0 && value.steps.length === 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['steps'],
+      message: 'Provide at least one phase or one step.',
+    })
+  }
+  if (value.steps.length > 0) {
+    const steps = value.steps as ProtocolStepDefinition[]
+    const dagResult = validateStepDag(steps)
+    if (!dagResult.valid) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['steps'],
+        message: `Cycle detected in step dependencies: ${dagResult.cycle?.join(' → ')}`,
+      })
+    }
+    const invalidRefs = validateStepRefs(steps)
+    for (const ref of invalidRefs) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['steps'],
+        message: `Step references unknown step ID: "${ref}"`,
+      })
+    }
+  }
+})

package/src/types/agent.ts

@@ -88,6 +88,8 @@ export interface Agent {
   monthlyBudget?: number | null
   dailyBudget?: number | null
   hourlyBudget?: number | null
+  /** Reference to a Goal in the goal hierarchy. */
+  goalId?: string | null
   autoRecovery?: boolean
   proactiveMemory?: boolean
   /** Auto-refresh a reviewed skill draft from meaningful chat turns for this agent. */
@@ -152,6 +154,14 @@ export interface Agent {
   dailySpend?: number
   /** Runtime-enriched: trailing 1-hour spend. Populated by GET /api/agents when hourlyBudget is set. */
   hourlySpend?: number
+  /** Persisted: accumulated spend in current monthly window (USD). Updated on each usage event. */
+  spentMonthlyCents?: number
+  /** Persisted: accumulated spend in current daily window (USD). Updated on each usage event. */
+  spentDailyCents?: number
+  /** Persisted: accumulated spend in current hourly window (USD). Updated on each usage event. */
+  spentHourlyCents?: number
+  /** Timestamp of last spend rollup; used to detect window resets. */
+  lastSpendRollupAt?: number
   maxFollowupChain?: number
 
   // Orchestrator Mode

package/src/types/app-settings.ts

@@ -148,6 +148,12 @@ export interface AppSettings {
   toolLoopCircuitBreaker?: number
   // Per-extension settings (keyed by extensionId)
   extensionSettings?: Record<string, Record<string, unknown>>
+  // Approval policies — opt-in governance gates for sensitive operations
+  approvalPolicies?: {
+    requireApprovalForAgentCreate?: boolean
+    requireApprovalForBudgetChange?: boolean
+    requireApprovalForDelegationEnable?: boolean
+  }
 }
 
 export interface EstopState {

package/src/types/approval.ts

@@ -7,6 +7,9 @@ export type ApprovalCategory =
   | 'task_tool'
   | 'human_loop'
   | 'connector_sender'
+  | 'agent_create'
+  | 'budget_change'
+  | 'delegation_enable'
 
 export interface ApprovalRequest {
   id: string

package/src/types/goal.ts

@@ -0,0 +1,30 @@
+export type GoalLevel = 'organization' | 'team' | 'project' | 'agent' | 'task'
+
+export type GoalStatus = 'active' | 'achieved' | 'abandoned'
+
+export interface Goal {
+  id: string
+  title: string
+  description?: string
+  level: GoalLevel
+  parentGoalId?: string | null
+  /** Link to a project (for project-level goals). */
+  projectId?: string | null
+  /** Link to an agent (for agent-level goals). */
+  agentId?: string | null
+  /** Link to a task (for task-level goals). */
+  taskId?: string | null
+  /** The concrete objective this goal achieves. */
+  objective: string
+  /** Constraints or guardrails on how the goal should be pursued. */
+  constraints?: string[]
+  /** How success is measured. */
+  successMetric?: string | null
+  /** Optional budget cap for this goal (USD). */
+  budgetUsd?: number | null
+  /** Optional deadline. */
+  deadlineAt?: number | null
+  status: GoalStatus
+  createdAt: number
+  updatedAt: number
+}

package/src/types/index.ts

@@ -13,4 +13,5 @@ export * from './skill'
 export * from './run'
 export * from './approval'
 export * from './misc'
+export * from './goal'
 export * from './swarmdock'

package/src/types/misc.ts

@@ -126,9 +126,9 @@ export interface Chatroom {
 
 export interface ActivityEntry {
   id: string
-  entityType: 'agent' | 'task' | 'connector' | 'session' | 'webhook' | 'schedule' | 'delegation' | 'swarm' | 'chatroom' | 'coordination'
+  entityType: 'agent' | 'task' | 'connector' | 'session' | 'webhook' | 'schedule' | 'delegation' | 'swarm' | 'chatroom' | 'coordination' | 'approval' | 'settings' | 'budget' | 'credential'
   entityId: string
-  action: 'created' | 'updated' | 'deleted' | 'started' | 'stopped' | 'queued' | 'completed' | 'failed' | 'archived' | 'restored' | 'approved' | 'rejected' | 'delegated' | 'queried' | 'spawned' | 'timeout' | 'cancelled' | 'incident' | 'running' | 'claimed'
+  action: 'created' | 'updated' | 'deleted' | 'started' | 'stopped' | 'queued' | 'completed' | 'failed' | 'archived' | 'restored' | 'approved' | 'rejected' | 'delegated' | 'queried' | 'spawned' | 'timeout' | 'cancelled' | 'incident' | 'running' | 'claimed' | 'configured' | 'budget_exceeded' | 'budget_warning'
   actor: 'user' | 'agent' | 'system' | 'daemon'
   actorId?: string
   summary: string

package/src/types/task.ts

@@ -35,6 +35,8 @@ export interface BoardTask {
   rootTaskId?: string | null
   projectId?: string
   goalContract?: GoalContract | null
+  /** Reference to a Goal in the goal hierarchy. Takes precedence over goalContract when set. */
+  goalId?: string | null
   cwd?: string | null
   file?: string | null
   sessionId?: string | null