@swarmclawai/swarmclaw 1.5.56 → 1.5.57

package/README.md

@@ -399,6 +399,20 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.57 Highlights
+
+This release closes the org-orchestration feature gap with Paperclip while keeping SwarmClaw's autonomous-assistant focus. Most additions are additive; nothing existing has changed shape.
+
+- **Workspace templates: full export/import bundle.** `src/lib/server/portability/{export,import}.ts` now round-trips agents, skills, schedules, **connectors** (with secret scrubbing), **chatrooms**, **MCP servers**, **projects**, **goals**, and an extension manifest reference. Manifest version bumped to `2`; v1 bundles still import. Connectors and MCP servers re-import with credentials stripped — the response payload now lists which records `needCredentials` so the UI can prompt. ID remapping handles cross-references (chatrooms → agents, schedules → agents, goals → projects/agents).
+- **Per-agent budget enforcement at enqueue.** New `src/lib/server/agents/agent-budget-hook.ts` mirrors the existing mission budget hook. When an agent has `budgetAction: 'block'` and any window (`hourlyBudget`/`dailyBudget`/`monthlyBudget`) is exhausted, autonomous enqueues now fail fast in `session-run-manager` instead of getting blocked deeper in the chat-turn pipeline. User-initiated chats still flow through (so users can talk to an agent that's hit its cap). Default `'warn'` behavior is unchanged.
+- **Goal hierarchy ancestry through Mission.** `Mission.goalId` is a new optional field. When a session has a `missionId` and the bound mission has a `goalId`, `main-agent-loop.ts` now walks `mission → goal → parentGoal → …` so the full Initiative/Project/Goal ancestry flows into the agent system prompt — previously only direct session-level goals were resolved.
+- **Billing codes / cost attribution.** `Mission`, `BoardTask`, `Session`, and `UsageRecord` accept an optional `billingCodes: string[]`. `resolveBillingCodesForSession` combines session + mission codes when usage is appended, and the new `GET /api/usage/by-code?codes=foo,bar&range=7d` endpoint rolls up cost per code (and per agent within each code). Lets users running multiple parallel projects answer "what did Project X cost?" across agents, missions, and ad-hoc chats.
+- **Customizable task workflow states.** New `WorkflowState` collection (`src/lib/server/tasks/workflow-state-repository.ts`) stores team-defined states like "Needs Review" or "Blocked on PM" that are orthogonal to `BoardTaskStatus` lifecycle. `BoardTask.workflowStateId` references one of seven defaults (Triage / Backlog / Todo / In Progress / Needs Review / Done / Cancelled) or any custom state. CRUD via `GET|POST|DELETE /api/task-workflow-states`. Atomic checkout via `task-checkout.ts` was already in place.
+- **Cross-agent delegation refusal policy.** `Chatroom.onRefusal` (`'reroute' | 'escalate' | 'human'`) and `Chatroom.escalationTargetAgentId` formalize what happens when a delegated agent declines work. `chatroom-refusal.ts` reroutes to another room member, escalates to a configured target, or surfaces a `human_loop` approval. Policy management at `POST /api/chatrooms/refusal-policy`; simulation at `PUT` for tests.
+- **Configuration version history.** Every `updateAgent` call now snapshots the prior agent state into `config-versions.json` (capped at 50 versions per entity). `GET /api/config-versions?entityKind=agent&entityId=...` lists history; `POST /api/config-versions/restore` rolls back. Foundation for extending to extensions, connectors, MCP servers, chatrooms, and projects.
+- **Multi-workspace scaffolding.** New `Workspace` registry with `GET|POST|PATCH|DELETE /api/workspaces` and `GET|POST /api/workspaces/active`. The default workspace seeds itself on first read; switching the active workspace persists to `workspace-registry.json`. **Note:** this is metadata only in v1.5.57 — actual data-dir forking per workspace is intentionally deferred (low-risk shipping).
+- **CLI manifest expanded.** New top-level groups: `workspaces`, `workflow-states`, `config-versions`, `cost-attribution`, `chatroom-policy`. Run `swarmclaw workspaces list`, `swarmclaw cost-attribution by-code --query codes=client-a,range=30d`, `swarmclaw config-versions list --query entityKind=agent,entityId=...`, etc. CLI route-coverage test passes.
+
 ### v1.5.56 Highlights
 
 - **Fix: TTS error responses are now proper JSON instead of a raw Buffer blob.** `POST /api/tts` and `POST /api/tts/stream` previously returned `500` with the error message wrapped in a `new NextResponse(string, ...)` that the CLI JSON-decoded into `{"type":"Buffer","data":[78,111,...]}`. Both routes now return `NextResponse.json({error}, {status: 500})`. Regression test added.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.56",
+  "version": "1.5.57",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/src/app/api/chatrooms/refusal-policy/route.ts

@@ -0,0 +1,43 @@
+import { NextResponse } from 'next/server'
+import { safeParseBody } from '@/lib/server/safe-parse-body'
+import { setChatroomRefusalPolicy, handleAgentRefusal } from '@/lib/server/chatrooms/chatroom-refusal'
+
+export const dynamic = 'force-dynamic'
+
+const VALID_POLICIES = new Set(['reroute', 'escalate', 'human'])
+
+export async function POST(req: Request) {
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const chatroomId = typeof body?.chatroomId === 'string' ? body.chatroomId : null
+  const policy = typeof body?.policy === 'string' ? body.policy : null
+  if (!chatroomId) return NextResponse.json({ error: 'chatroomId required' }, { status: 400 })
+  if (!policy || !VALID_POLICIES.has(policy)) {
+    return NextResponse.json({ error: 'policy must be reroute|escalate|human' }, { status: 400 })
+  }
+  const escalationTargetAgentId = typeof body?.escalationTargetAgentId === 'string'
+    ? body.escalationTargetAgentId
+    : null
+  const room = setChatroomRefusalPolicy(
+    chatroomId,
+    policy as 'reroute' | 'escalate' | 'human',
+    escalationTargetAgentId,
+  )
+  if (!room) return NextResponse.json({ error: 'chatroom not found' }, { status: 404 })
+  return NextResponse.json({ chatroom: room })
+}
+
+export async function PUT(req: Request) {
+  // Trigger a refusal handling decision (used by agent runtime + tests).
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const chatroomId = typeof body?.chatroomId === 'string' ? body.chatroomId : null
+  const refusingAgentId = typeof body?.refusingAgentId === 'string' ? body.refusingAgentId : null
+  const taskOrTopic = typeof body?.taskOrTopic === 'string' ? body.taskOrTopic : ''
+  const reason = typeof body?.reason === 'string' ? body.reason : 'unspecified'
+  if (!chatroomId || !refusingAgentId) {
+    return NextResponse.json({ error: 'chatroomId and refusingAgentId required' }, { status: 400 })
+  }
+  const decision = handleAgentRefusal({ chatroomId, refusingAgentId, taskOrTopic, reason })
+  return NextResponse.json({ decision })
+}

package/src/app/api/config-versions/restore/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from 'next/server'
+import { safeParseBody } from '@/lib/server/safe-parse-body'
+import { getVersion } from '@/lib/server/config-versions/config-version-repository'
+import { updateAgent } from '@/lib/server/agents/agent-service'
+
+export const dynamic = 'force-dynamic'
+
+export async function POST(req: Request) {
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const versionId = typeof body?.versionId === 'string' ? body.versionId : null
+  if (!versionId) return NextResponse.json({ error: 'versionId required' }, { status: 400 })
+
+  const version = getVersion(versionId)
+  if (!version) return NextResponse.json({ error: 'version not found' }, { status: 404 })
+
+  if (version.entityKind === 'agent') {
+    const restored = updateAgent(version.entityId, version.snapshot)
+    if (!restored) return NextResponse.json({ error: 'agent not found' }, { status: 404 })
+    return NextResponse.json({ ok: true, restored: { kind: 'agent', id: version.entityId } })
+  }
+
+  return NextResponse.json({
+    error: `Restore not yet implemented for kind=${version.entityKind}`,
+  }, { status: 501 })
+}

package/src/app/api/config-versions/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from 'next/server'
+import { listVersionsForEntity } from '@/lib/server/config-versions/config-version-repository'
+import type { VersionedEntityKind } from '@/types/config-version'
+
+export const dynamic = 'force-dynamic'
+
+const VALID_KINDS = new Set<VersionedEntityKind>([
+  'agent', 'extension', 'connector', 'mcp_server', 'chatroom', 'project',
+])
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const kind = searchParams.get('entityKind') as VersionedEntityKind | null
+  const id = searchParams.get('entityId')
+  if (!kind || !VALID_KINDS.has(kind)) {
+    return NextResponse.json({ error: 'entityKind required (agent|extension|connector|mcp_server|chatroom|project)' }, { status: 400 })
+  }
+  if (!id) return NextResponse.json({ error: 'entityId required' }, { status: 400 })
+  const versions = listVersionsForEntity(kind, id)
+  return NextResponse.json({ versions })
+}

package/src/app/api/task-workflow-states/route.ts

@@ -0,0 +1,69 @@
+import { NextResponse } from 'next/server'
+import { genId } from '@/lib/id'
+import { safeParseBody } from '@/lib/server/safe-parse-body'
+import {
+  deleteWorkflowState,
+  listWorkflowStates,
+  resetWorkflowStatesToDefaults,
+  upsertWorkflowState,
+} from '@/lib/server/tasks/workflow-state-repository'
+import type { WorkflowState, WorkflowStateCategory } from '@/types/workflow-state'
+
+export const dynamic = 'force-dynamic'
+
+const VALID_CATEGORIES = new Set<WorkflowStateCategory>([
+  'triage', 'backlog', 'unstarted', 'started', 'completed', 'cancelled',
+])
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const projectId = searchParams.get('projectId')
+  const states = listWorkflowStates(
+    projectId ? { projectId } : undefined,
+  )
+  return NextResponse.json({ states })
+}
+
+export async function POST(req: Request) {
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const label = asString(body?.label)
+  const categoryRaw = asString(body?.category) as WorkflowStateCategory | null
+  if (!label) return NextResponse.json({ error: 'label is required' }, { status: 400 })
+  if (!categoryRaw || !VALID_CATEGORIES.has(categoryRaw)) {
+    return NextResponse.json({ error: 'category must be one of triage|backlog|unstarted|started|completed|cancelled' }, { status: 400 })
+  }
+  const id = asString(body?.id) || genId()
+  const now = Date.now()
+  const state: WorkflowState = {
+    id,
+    label,
+    category: categoryRaw,
+    projectId: asString(body?.projectId),
+    color: asString(body?.color),
+    position: typeof body?.position === 'number' ? body.position : undefined,
+    autoArchiveAfterDays: typeof body?.autoArchiveAfterDays === 'number' ? body.autoArchiveAfterDays : null,
+    createdAt: now,
+    updatedAt: now,
+  }
+  const saved = upsertWorkflowState(state)
+  return NextResponse.json({ state: saved })
+}
+
+export async function DELETE(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const id = searchParams.get('id')
+  if (id) {
+    const removed = deleteWorkflowState(id)
+    return NextResponse.json({ ok: removed })
+  }
+  if (searchParams.get('reset') === 'true') {
+    resetWorkflowStatesToDefaults()
+    return NextResponse.json({ ok: true, reset: true })
+  }
+  return NextResponse.json({ error: 'id or reset=true required' }, { status: 400 })
+}

package/src/app/api/usage/by-code/route.ts

@@ -0,0 +1,32 @@
+import { NextResponse } from 'next/server'
+import { listObservedBillingCodes, rollupCostByBillingCode } from '@/lib/server/usage/cost-attribution'
+
+export const dynamic = 'force-dynamic'
+
+const RANGE_MS: Record<string, number> = {
+  '24h': 24 * 60 * 60 * 1000,
+  '7d': 7 * 24 * 60 * 60 * 1000,
+  '30d': 30 * 24 * 60 * 60 * 1000,
+  'all': Number.POSITIVE_INFINITY,
+}
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const codesParam = searchParams.get('codes')
+  const codes = codesParam
+    ? codesParam.split(',').map((s) => s.trim()).filter(Boolean)
+    : undefined
+  const rangeParam = searchParams.get('range') ?? 'all'
+  const rangeMs = RANGE_MS[rangeParam] ?? Number.POSITIVE_INFINITY
+  const sinceMs = Number.isFinite(rangeMs) ? Date.now() - rangeMs : 0
+
+  const rollups = rollupCostByBillingCode({ codes, sinceMs })
+  const observed = listObservedBillingCodes()
+
+  return NextResponse.json({
+    range: rangeParam,
+    codes: codes ?? null,
+    rollups,
+    observedCodes: observed,
+  })
+}

package/src/app/api/workspaces/active/route.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from 'next/server'
+import { safeParseBody } from '@/lib/server/safe-parse-body'
+import { getActiveWorkspace, setActiveWorkspace } from '@/lib/server/workspaces/workspace-registry'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET() {
+  return NextResponse.json({ workspace: getActiveWorkspace() })
+}
+
+export async function POST(req: Request) {
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const id = typeof body?.id === 'string' ? body.id : null
+  if (!id) return NextResponse.json({ error: 'id required' }, { status: 400 })
+  const workspace = setActiveWorkspace(id)
+  if (!workspace) return NextResponse.json({ error: 'workspace not found' }, { status: 404 })
+  return NextResponse.json({ workspace })
+}

package/src/app/api/workspaces/route.ts

@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server'
+import { safeParseBody } from '@/lib/server/safe-parse-body'
+import {
+  createWorkspace,
+  deleteWorkspace,
+  listWorkspaces,
+  updateWorkspace,
+} from '@/lib/server/workspaces/workspace-registry'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET() {
+  return NextResponse.json({ workspaces: listWorkspaces() })
+}
+
+export async function POST(req: Request) {
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const name = typeof body?.name === 'string' && body.name.trim() ? body.name.trim() : null
+  if (!name) return NextResponse.json({ error: 'name required' }, { status: 400 })
+  const workspace = createWorkspace({
+    name,
+    description: typeof body?.description === 'string' ? body.description : undefined,
+    color: typeof body?.color === 'string' ? body.color : undefined,
+  })
+  return NextResponse.json({ workspace })
+}
+
+export async function PATCH(req: Request) {
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const id = typeof body?.id === 'string' ? body.id : null
+  if (!id) return NextResponse.json({ error: 'id required' }, { status: 400 })
+  const updated = updateWorkspace(id, body as Record<string, unknown>)
+  if (!updated) return NextResponse.json({ error: 'workspace not found' }, { status: 404 })
+  return NextResponse.json({ workspace: updated })
+}
+
+export async function DELETE(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const id = searchParams.get('id')
+  if (!id) return NextResponse.json({ error: 'id required' }, { status: 400 })
+  const removed = deleteWorkspace(id)
+  if (!removed) return NextResponse.json({ error: 'cannot delete default or unknown workspace' }, { status: 400 })
+  return NextResponse.json({ ok: true })
+}

package/src/cli/index.js

@@ -821,6 +821,50 @@ const COMMAND_GROUPS = [
       cmd('instantiate', 'POST', '/missions/templates/:id/instantiate', 'Create a mission from a template', { expectsJsonBody: true }),
     ],
   },
+  {
+    name: 'workspaces',
+    description: 'Manage logical workspaces (multi-workspace scaffolding)',
+    commands: [
+      cmd('list', 'GET', '/workspaces', 'List workspaces'),
+      cmd('create', 'POST', '/workspaces', 'Create a workspace', { expectsJsonBody: true }),
+      cmd('update', 'PATCH', '/workspaces', 'Update a workspace', { expectsJsonBody: true }),
+      cmd('delete', 'DELETE', '/workspaces', 'Delete a workspace (use --query id=...)'),
+      cmd('active', 'GET', '/workspaces/active', 'Get the active workspace'),
+      cmd('set-active', 'POST', '/workspaces/active', 'Set the active workspace', { expectsJsonBody: true }),
+    ],
+  },
+  {
+    name: 'workflow-states',
+    description: 'Manage customizable task workflow states',
+    commands: [
+      cmd('list', 'GET', '/task-workflow-states', 'List workflow states'),
+      cmd('create', 'POST', '/task-workflow-states', 'Create or update a workflow state', { expectsJsonBody: true }),
+      cmd('delete', 'DELETE', '/task-workflow-states', 'Delete a workflow state (use --query id=... or --query reset=true)'),
+    ],
+  },
+  {
+    name: 'config-versions',
+    description: 'Inspect and restore configuration version history',
+    commands: [
+      cmd('list', 'GET', '/config-versions', 'List versions for an entity (use --query entityKind=agent,entityId=...)'),
+      cmd('restore', 'POST', '/config-versions/restore', 'Restore an entity to a prior version', { expectsJsonBody: true }),
+    ],
+  },
+  {
+    name: 'cost-attribution',
+    description: 'Aggregate LLM cost by billing-code tags',
+    commands: [
+      cmd('by-code', 'GET', '/usage/by-code', 'Roll up cost by billing code (use --query codes=foo,bar,range=7d)'),
+    ],
+  },
+  {
+    name: 'chatroom-policy',
+    description: 'Configure chatroom delegation refusal policies',
+    commands: [
+      cmd('set', 'POST', '/chatrooms/refusal-policy', 'Set onRefusal policy for a chatroom', { expectsJsonBody: true }),
+      cmd('simulate', 'PUT', '/chatrooms/refusal-policy', 'Simulate a refusal-handling decision', { expectsJsonBody: true }),
+    ],
+  },
   {
     name: 'swarmfeed',
     description: 'SwarmFeed social network',

package/src/cli/spec.js

@@ -559,6 +559,45 @@ const COMMAND_GROUPS = {
       delete: { description: 'Delete a goal', method: 'DELETE', path: '/goals/:id', params: ['id'] },
     },
   },
+  workspaces: {
+    description: 'Manage logical workspaces (multi-workspace scaffolding)',
+    commands: {
+      list: { description: 'List workspaces', method: 'GET', path: '/workspaces' },
+      create: { description: 'Create a workspace', method: 'POST', path: '/workspaces' },
+      update: { description: 'Update a workspace', method: 'PATCH', path: '/workspaces' },
+      delete: { description: 'Delete a workspace', method: 'DELETE', path: '/workspaces' },
+      active: { description: 'Get the active workspace', method: 'GET', path: '/workspaces/active' },
+      'set-active': { description: 'Set the active workspace', method: 'POST', path: '/workspaces/active' },
+    },
+  },
+  'workflow-states': {
+    description: 'Manage customizable task workflow states',
+    commands: {
+      list: { description: 'List workflow states', method: 'GET', path: '/task-workflow-states' },
+      create: { description: 'Create or update a workflow state', method: 'POST', path: '/task-workflow-states' },
+      delete: { description: 'Delete a workflow state (or pass --query reset=true to restore defaults)', method: 'DELETE', path: '/task-workflow-states' },
+    },
+  },
+  'config-versions': {
+    description: 'Inspect and restore configuration version history',
+    commands: {
+      list: { description: 'List versions for an entity (--query entityKind=agent,entityId=...)', method: 'GET', path: '/config-versions' },
+      restore: { description: 'Restore an entity to a prior version', method: 'POST', path: '/config-versions/restore' },
+    },
+  },
+  'cost-attribution': {
+    description: 'Aggregate cost by billing-code tags',
+    commands: {
+      'by-code': { description: 'Roll up cost by billing code (--query codes=foo,bar,range=7d)', method: 'GET', path: '/usage/by-code' },
+    },
+  },
+  'chatroom-policy': {
+    description: 'Configure chatroom delegation refusal policies',
+    commands: {
+      set: { description: 'Set onRefusal policy for a chatroom', method: 'POST', path: '/chatrooms/refusal-policy' },
+      simulate: { description: 'Simulate a refusal-handling decision', method: 'PUT', path: '/chatrooms/refusal-policy' },
+    },
+  },
   missions: {
     description: 'Manage autonomous missions',
     commands: {

package/src/lib/server/agents/agent-budget-hook.ts

@@ -0,0 +1,29 @@
+import { getAgent } from '@/lib/server/agents/agent-repository'
+import { checkAgentBudgetLimits } from '@/lib/server/cost'
+
+export interface AgentBudgetHookResult {
+  allow: boolean
+  reason?: string
+}
+
+/**
+ * Pure, synchronous check suitable for the hot enqueue path. When an agent has
+ * `budgetAction: 'block'` set and any window is exhausted, denies the run
+ * before we even queue it. Mirrors `checkMissionBudgetForSession` so autonomous
+ * runs can fail fast instead of waiting until chat-turn-preparation.
+ *
+ * For `budgetAction: 'warn'` (default), always allows — the warn-only behavior
+ * is handled later in the turn pipeline so users see a status event.
+ */
+export function checkAgentBudgetForSession(agentId: string | null | undefined): AgentBudgetHookResult {
+  if (!agentId) return { allow: true }
+  const agent = getAgent(agentId)
+  if (!agent) return { allow: true }
+  if ((agent.budgetAction || 'warn') !== 'block') return { allow: true }
+
+  const summary = checkAgentBudgetLimits(agent)
+  if (summary.exceeded.length === 0) return { allow: true }
+
+  const blockedMessage = summary.exceeded.map((entry) => entry.message).join(' ')
+  return { allow: false, reason: blockedMessage }
+}

package/src/lib/server/agents/agent-service.ts

@@ -16,6 +16,7 @@ import {
   saveAgent,
 } from '@/lib/server/agents/agent-repository'
 import { logActivity } from '@/lib/server/activity/activity-log'
+import { snapshotVersion } from '@/lib/server/config-versions/config-version-repository'
 import { getAgentSpendWindows } from '@/lib/server/cost'
 import { serviceFail, serviceOk } from '@/lib/server/service-result'
 import { listSessions, saveSession } from '@/lib/server/sessions/session-repository'
@@ -205,8 +206,10 @@ export function createAgent(input: {
 }
 
 export function updateAgent(agentId: string, body: Record<string, unknown>): Agent | null {
+  let preUpdateSnapshot: Agent | null = null
   const updated = patchAgent(agentId, (current) => {
     if (!current) return null
+    if (!preUpdateSnapshot) preUpdateSnapshot = current
     if (body.projectId === undefined && Array.isArray(body.projectIds) && body.projectIds.length > 0) {
       const first = body.projectIds[0]
       if (typeof first === 'string' && first.trim()) {
@@ -317,6 +320,19 @@ export function updateAgent(agentId: string, body: Record<string, unknown>): Age
   })
   if (!updated) return null
 
+  if (preUpdateSnapshot) {
+    try {
+      snapshotVersion({
+        entityKind: 'agent',
+        entityId: agentId,
+        snapshot: preUpdateSnapshot as unknown as Record<string, unknown>,
+        actor: 'user',
+      })
+    } catch (err) {
+      log.warn('agent-service', `Config version snapshot failed for agent ${agentId}: ${err instanceof Error ? err.message : err}`)
+    }
+  }
+
   if (updated.threadSessionId) {
     ensureAgentThreadSession(agentId)
     updateThreadShortcutSession(agentId, updated)

package/src/lib/server/agents/main-agent-loop.ts

@@ -17,6 +17,7 @@ import { syncMainLoopToRunContext } from '@/lib/server/run-context'
 import { buildExecutionBrief, buildExecutionBriefContextBlock } from '@/lib/server/execution-brief'
 import { cleanText, cleanMultiline } from '@/lib/server/text-normalization'
 import { getGoalById, resolveEffectiveGoal } from '@/lib/server/goals/goal-service'
+import { getMission } from '@/lib/server/missions/mission-repository'
 
 const LEGACY_META_LINE_RE = /\[(?:MAIN_LOOP_META|MAIN_LOOP_PLAN|MAIN_LOOP_REVIEW|AGENT_HEARTBEAT_META|AUTONOMY_TICK)\]\s*(\{[^\n]*\})?/i
 const AUTONOMY_TICK_RE = /\[AUTONOMY_TICK\]\s*(\{[^\n]*\})/i
@@ -513,6 +514,13 @@ function resolveSessionGoalRecord(session: Session | null | undefined): Record<s
     ? String(s.missionId).trim()
     : ''
   if (legacyMissionId) {
+    // Prefer the mission's bound goal (so Initiative/Project ancestry flows in)
+    // over treating the missionId itself as a goal id.
+    const mission = getMission(legacyMissionId)
+    if (mission?.goalId) {
+      const boundGoal = getGoalById(mission.goalId)
+      if (boundGoal) return boundGoal as unknown as Record<string, unknown>
+    }
     const missionGoal = getGoalById(legacyMissionId)
     if (missionGoal) return missionGoal as unknown as Record<string, unknown>
   }

package/src/lib/server/chat-execution/chat-turn-finalization.ts

@@ -49,6 +49,7 @@ import {
   replaceAllMessages,
 } from '@/lib/server/messages/message-repository'
 import { appendUsage } from '@/lib/server/usage/usage-repository'
+import { resolveBillingCodesForSession } from '@/lib/server/usage/resolve-billing-codes'
 import { synchronizeWorkingStateForTurn } from '@/lib/server/working-state/service'
 import { notify } from '@/lib/server/ws-hub'
 import { selectKnowledgeCitations } from '@/lib/server/knowledge-sources'
@@ -223,6 +224,7 @@ export async function finalizeChatTurn(params: {
         durationMs,
         agentId: sessionForRun.agentId || null,
         projectId: sessionForRun.projectId || null,
+        billingCodes: resolveBillingCodesForSession(sessionForRun),
       }
       appendUsage(sessionId, usageRecord)
       emit({

package/src/lib/server/chat-execution/post-stream-finalization.ts

@@ -14,6 +14,7 @@ import { extractSuggestions } from '@/lib/server/suggestions'
 import type { StructuredToolInterface } from '@langchain/core/tools'
 import { estimateCost, buildExtensionDefinitionCosts } from '@/lib/server/cost'
 import { appendUsage } from '@/lib/server/usage/usage-repository'
+import { resolveBillingCodesForSession } from '@/lib/server/usage/resolve-billing-codes'
 import { runCapabilityHook } from '@/lib/server/native-capabilities'
 import {
   shouldForceExternalServiceSummary,
@@ -217,6 +218,7 @@ export async function finalizeStreamResult(opts: FinalizeStreamResultOpts): Prom
       durationMs: Date.now() - startTs,
       agentId: session.agentId || null,
       projectId: session.projectId || null,
+      billingCodes: resolveBillingCodesForSession(session),
       extensionDefinitionCosts,
       extensionInvocations: state.extensionInvocations.length > 0 ? state.extensionInvocations : undefined,
     }

package/src/lib/server/chatrooms/chatroom-refusal.ts

@@ -0,0 +1,108 @@
+import { loadChatroom, upsertChatroom } from '@/lib/server/chatrooms/chatroom-repository'
+import { logActivity } from '@/lib/server/activity/activity-log'
+import { requestApproval } from '@/lib/server/approvals'
+import { log } from '@/lib/server/logger'
+import type { Chatroom } from '@/types'
+
+const TAG = 'chatroom-refusal'
+
+export interface RefusalDecision {
+  action: 'reroute' | 'escalate' | 'human' | 'noop'
+  /** Agent id to retry the work with, when applicable. */
+  nextAgentId?: string | null
+  /** Approval id when surfaced to a human. */
+  approvalId?: string | null
+  reason?: string
+}
+
+/**
+ * Apply the chatroom's `onRefusal` policy when an assigned agent declines or
+ * returns a refusal signal for a delegated work item. Records the decision in
+ * the activity log and returns the next action for the caller.
+ */
+export function handleAgentRefusal(input: {
+  chatroomId: string
+  refusingAgentId: string
+  taskOrTopic: string
+  reason: string
+}): RefusalDecision {
+  const room = loadChatroom(input.chatroomId)
+  if (!room) {
+    log.warn(TAG, `Refusal received for unknown chatroom ${input.chatroomId}`)
+    return { action: 'noop' }
+  }
+
+  const policy = room.onRefusal ?? 'reroute'
+
+  if (policy === 'human') {
+    const approval = requestApproval({
+      category: 'human_loop',
+      title: `Chatroom "${room.name}" refusal needs human input`,
+      description: `Agent ${input.refusingAgentId} refused work: "${input.taskOrTopic}". Reason: ${input.reason}`,
+      data: {
+        chatroomId: room.id,
+        refusingAgentId: input.refusingAgentId,
+        taskOrTopic: input.taskOrTopic,
+        reason: input.reason,
+      },
+    })
+    logActivity({
+      entityType: 'chatroom',
+      entityId: room.id,
+      action: 'refusal_escalated_human',
+      actor: 'system',
+      summary: `Refusal from ${input.refusingAgentId} surfaced as approval ${approval.id}`,
+    })
+    return { action: 'human', approvalId: approval.id, reason: input.reason }
+  }
+
+  if (policy === 'escalate') {
+    const target = room.escalationTargetAgentId
+    if (target && target !== input.refusingAgentId && room.agentIds.includes(target)) {
+      logActivity({
+        entityType: 'chatroom',
+        entityId: room.id,
+        action: 'refusal_escalated',
+        actor: 'system',
+        summary: `Refusal from ${input.refusingAgentId} escalated to ${target}`,
+      })
+      return { action: 'escalate', nextAgentId: target, reason: input.reason }
+    }
+    // Fall through to reroute when no escalation target available.
+  }
+
+  // reroute (or escalate fallback): pick any other room member.
+  const candidate = room.agentIds.find((id) => id !== input.refusingAgentId)
+  if (candidate) {
+    logActivity({
+      entityType: 'chatroom',
+      entityId: room.id,
+      action: 'refusal_rerouted',
+      actor: 'system',
+      summary: `Refusal from ${input.refusingAgentId} rerouted to ${candidate}`,
+    })
+    return { action: 'reroute', nextAgentId: candidate, reason: input.reason }
+  }
+
+  return { action: 'noop', reason: 'no alternative agent available' }
+}
+
+/**
+ * Sets or updates a chatroom's onRefusal policy and persists the change.
+ */
+export function setChatroomRefusalPolicy(
+  chatroomId: string,
+  policy: NonNullable<Chatroom['onRefusal']>,
+  escalationTargetAgentId?: string | null,
+): Chatroom | null {
+  const room = loadChatroom(chatroomId)
+  if (!room) return null
+  const next: Chatroom = {
+    ...room,
+    onRefusal: policy,
+    escalationTargetAgentId: escalationTargetAgentId ?? room.escalationTargetAgentId ?? null,
+    updatedAt: Date.now(),
+  }
+  upsertChatroom(chatroomId, next)
+  return next
+}