@swarmclawai/swarmclaw 0.7.3 → 0.7.5

package/bin/update-cmd.js

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
 'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
 
-const { execSync } = require('node:child_process')
+const { execSync, execFileSync } = require('node:child_process')
 const path = require('node:path')
+const {
+  dependenciesChanged,
+  detectPackageManager,
+  getGlobalUpdateSpec,
+  getInstallCommand,
+} = require('./package-manager.js')
 
 const PKG_ROOT = path.resolve(__dirname, '..')
+const PACKAGE_NAME = '@swarmclawai/swarmclaw'
 const RELEASE_TAG_RE = /^v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/
+const PACKAGE_MANAGER = detectPackageManager(PKG_ROOT)
 
 function run(cmd) {
   return execSync(cmd, { encoding: 'utf-8', cwd: PKG_ROOT, timeout: 60_000 }).trim()
@@ -27,15 +36,37 @@ function getLatestStableTag() {
   return tags.find((t) => RELEASE_TAG_RE.test(t)) || null
 }
 
+function runRegistrySelfUpdate(
+  packageManager = PACKAGE_MANAGER,
+  execImpl = execFileSync,
+  logger = { log, logError },
+) {
+  const update = getGlobalUpdateSpec(packageManager, PACKAGE_NAME)
+  logger.log(`No git checkout detected. Updating the global ${PACKAGE_NAME} install via ${packageManager}...`)
+  try {
+    execImpl(update.command, update.args, {
+      cwd: PKG_ROOT,
+      stdio: 'inherit',
+      timeout: 120_000,
+    })
+    logger.log(`Global update complete via ${packageManager}.`)
+    logger.log('Restart the server to apply changes: swarmclaw server stop && swarmclaw server start')
+    return 0
+  } catch (err) {
+    logger.logError(`Registry update failed: ${err.message}`)
+    logger.logError(`Retry manually with: ${update.display}`)
+    return 1
+  }
+}
+
 function main() {
   const args = process.argv.slice(3)
   if (args.includes('-h') || args.includes('--help')) {
     console.log(`
 Usage: swarmclaw update
 
-Pull the latest SwarmClaw release via git.
-Prefers stable release tags (v*); falls back to origin/main.
-Runs npm install if package files changed.
+If running from a git checkout, pull the latest SwarmClaw release tag.
+If running from a registry install, update the global package with ${PACKAGE_MANAGER}.
 `.trim())
     process.exit(0)
   }
@@ -44,8 +75,7 @@ Runs npm install if package files changed.
   try {
     run('git rev-parse --git-dir')
   } catch {
-    logError('Not a git repository. Cannot update.')
-    process.exit(1)
+    process.exit(runRegistrySelfUpdate(PACKAGE_MANAGER))
   }
 
   const beforeRef = run('git rev-parse HEAD')
@@ -105,9 +135,10 @@ Runs npm install if package files changed.
   // Install deps if package files changed
   try {
     const diff = run(`git diff --name-only ${beforeSha}..HEAD`)
-    if (diff.includes('package-lock.json') || diff.includes('package.json')) {
-      log('Package files changed — running npm install...')
-      execSync('npm install --omit=dev', { cwd: PKG_ROOT, stdio: 'inherit', timeout: 120_000 })
+    if (dependenciesChanged(diff)) {
+      const install = getInstallCommand(PACKAGE_MANAGER, true)
+      log(`Package files changed — running ${PACKAGE_MANAGER} install...`)
+      execFileSync(install.command, install.args, { cwd: PKG_ROOT, stdio: 'inherit', timeout: 120_000 })
     }
   } catch {
     // If diff fails, skip install check
@@ -117,4 +148,11 @@ Runs npm install if package files changed.
   log('Restart the server to apply changes: swarmclaw server stop && swarmclaw server start')
 }
 
-main()
+if (require.main === module) {
+  main()
+}
+
+module.exports = {
+  main,
+  runRegistrySelfUpdate,
+}

package/bin/update-cmd.test.js

@@ -0,0 +1,55 @@
+'use strict'
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+
+const { runRegistrySelfUpdate } = require('./update-cmd.js')
+
+test('runRegistrySelfUpdate executes the manager-specific global update command', () => {
+  const messages = []
+  let captured = null
+
+  const exitCode = runRegistrySelfUpdate(
+    'pnpm',
+    (command, args, options) => {
+      captured = { command, args, options }
+    },
+    {
+      log: (message) => messages.push(`log:${message}`),
+      logError: (message) => messages.push(`err:${message}`),
+    },
+  )
+
+  assert.equal(exitCode, 0)
+  assert.deepEqual(captured, {
+    command: 'pnpm',
+    args: ['add', '-g', '@swarmclawai/swarmclaw@latest'],
+    options: {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+      timeout: 120_000,
+    },
+  })
+  assert.match(messages.join('\n'), /updating the global @swarmclawai\/swarmclaw install via pnpm/i)
+  assert.match(messages.join('\n'), /global update complete via pnpm/i)
+})
+
+test('runRegistrySelfUpdate reports a manual retry command when the registry update fails', () => {
+  const messages = []
+
+  const exitCode = runRegistrySelfUpdate(
+    'bun',
+    () => {
+      throw new Error('spawn bun ENOENT')
+    },
+    {
+      log: (message) => messages.push(`log:${message}`),
+      logError: (message) => messages.push(`err:${message}`),
+    },
+  )
+
+  assert.equal(exitCode, 1)
+  assert.match(messages.join('\n'), /registry update failed: spawn bun ENOENT/i)
+  assert.match(messages.join('\n'), /retry manually with: bun add -g @swarmclawai\/swarmclaw@latest/i)
+})

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/swarmclawai/swarmclaw.git"
@@ -46,13 +50,14 @@
     "start": "next start",
     "start:standalone": "node .next/standalone/server.js",
     "benchmark:autonomy": "node ./scripts/benchmark-autonomy-harness.mjs",
+    "benchmark:agent-regression": "node --import tsx ./scripts/run-agent-regression-suite.ts",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
     "lint:baseline": "node ./scripts/lint-baseline.mjs check",
     "lint:baseline:update": "node ./scripts/lint-baseline.mjs update",
     "cli": "node ./bin/swarmclaw.js",
-    "test:cli": "node --test src/cli/index.test.js",
-    "test:openclaw": "tsx --test src/lib/server/connectors/openclaw.test.ts src/lib/openclaw-endpoint.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/server/task-validation.test.ts src/lib/server/task-quality-gate.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts",
+    "test:cli": "node --test src/cli/*.test.js bin/*.test.js",
+    "test:openclaw": "tsx --test src/lib/openclaw-agent-id.test.ts src/lib/openclaw-endpoint.test.ts src/lib/server/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw-agent-resolver.test.ts src/lib/server/openclaw-skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/task-quality-gate.test.ts src/lib/server/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",
     "postinstall": "node ./scripts/postinstall.mjs"
   },

package/scripts/postinstall.mjs

@@ -1,6 +1,32 @@
 #!/usr/bin/env node
 
+import { writeFileSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
+const INSTALL_METADATA_FILE = '.swarmclaw-install.json'
+
+function detectPackageManagerFromUserAgent(userAgent) {
+  const normalized = String(userAgent || '').toLowerCase()
+  if (normalized.startsWith('pnpm/')) return 'pnpm'
+  if (normalized.startsWith('yarn/')) return 'yarn'
+  if (normalized.startsWith('bun/')) return 'bun'
+  if (normalized.startsWith('npm/')) return 'npm'
+  return null
+}
+
+const installedWith = detectPackageManagerFromUserAgent(process.env.npm_config_user_agent) || 'npm'
+
+try {
+  writeFileSync(
+    new URL(`../${INSTALL_METADATA_FILE}`, import.meta.url),
+    JSON.stringify({
+      packageManager: installedWith,
+      installedAt: new Date().toISOString(),
+    }, null, 2),
+    'utf8',
+  )
+} catch {
+  // Ignore metadata write failures for install resilience.
+}
 
 const result = spawnSync('npm', ['rebuild', 'better-sqlite3', '--silent'], {
   stdio: 'ignore',

package/src/app/api/agents/[id]/route.ts

@@ -23,6 +23,23 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
         body.apiEndpoint,
       )
     }
+    if (body.routingTargets !== undefined && Array.isArray(body.routingTargets)) {
+      agent.routingTargets = body.routingTargets.map((target: Record<string, unknown>, index: number) => ({
+        id: typeof target.id === 'string' && target.id.trim() ? target.id.trim() : `route-${index + 1}`,
+        label: typeof target.label === 'string' ? target.label : undefined,
+        role: target.role,
+        provider: (typeof target.provider === 'string' && target.provider.trim() ? target.provider : agent.provider),
+        model: typeof target.model === 'string' ? target.model : '',
+        credentialId: target.credentialId ?? null,
+        fallbackCredentialIds: Array.isArray(target.fallbackCredentialIds) ? target.fallbackCredentialIds : [],
+        apiEndpoint: normalizeProviderEndpoint(
+          typeof target.provider === 'string' ? target.provider : agent.provider,
+          typeof target.apiEndpoint === 'string' ? target.apiEndpoint : null,
+        ),
+        gatewayProfileId: target.gatewayProfileId ?? null,
+        priority: typeof target.priority === 'number' ? target.priority : index + 1,
+      }))
+    }
     delete (agent as Record<string, unknown>).isOrchestrator
     agent.isOrchestrator = agent.platformAssignScope === 'all'
     delete (agent as Record<string, unknown>).id

package/src/app/api/agents/[id]/thread/route.ts

@@ -1,96 +1,13 @@
 import { NextResponse } from 'next/server'
-import { genId } from '@/lib/id'
-import { loadAgents, saveAgents, loadSessions, saveSessions } from '@/lib/server/storage'
-import { WORKSPACE_DIR } from '@/lib/server/data-dir'
+import { ensureAgentThreadSession } from '@/lib/server/agent-thread-session'
 
 export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id: agentId } = await params
-  const agents = loadAgents()
-  const agent = agents[agentId]
-  if (!agent) {
-    return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
-  }
-
   const body = await req.json().catch(() => ({}))
   const user = body.user || 'default'
-  const sessions = loadSessions()
-
-  // If the agent already has a shortcut chat session, return it.
-  if (agent.threadSessionId && sessions[agent.threadSessionId]) {
-    const existing = sessions[agent.threadSessionId] as Record<string, unknown>
-    let changed = false
-    if (existing.shortcutForAgentId !== agentId) {
-      existing.shortcutForAgentId = agentId
-      changed = true
-    }
-    if (existing.name !== agent.name) {
-      existing.name = agent.name
-      changed = true
-    }
-    if (changed) saveSessions(sessions)
-    return NextResponse.json(existing)
-  }
-
-  // Legacy fallback for older shortcut sessions that were named using the
-  // old agent-thread convention before the explicit link was persisted.
-  const existing = Object.values(sessions).find(
-    (s: Record<string, unknown>) =>
-      (
-        s.shortcutForAgentId === agentId
-        || s.name === `agent-thread:${agentId}`
-      )
-      && s.user === user
-  )
-  if (existing) {
-    agent.threadSessionId = (existing as Record<string, unknown>).id as string
-    agent.updatedAt = Date.now()
-    saveAgents(agents)
-    let changed = false
-    const existingRecord = existing as Record<string, unknown>
-    if (existingRecord.shortcutForAgentId !== agentId) {
-      existingRecord.shortcutForAgentId = agentId
-      changed = true
-    }
-    if (existingRecord.name !== agent.name) {
-      existingRecord.name = agent.name
-      changed = true
-    }
-    if (changed) saveSessions(sessions)
-    return NextResponse.json(existing)
-  }
-
-  // Create a new shortcut chat session for this agent.
-  const sessionId = `agent-chat-${agentId}-${genId()}`
-  const now = Date.now()
-  const session = {
-    id: sessionId,
-    name: agent.name,
-    shortcutForAgentId: agentId,
-    cwd: WORKSPACE_DIR,
-    user: user,
-    provider: agent.provider,
-    model: agent.model,
-    credentialId: agent.credentialId || null,
-    fallbackCredentialIds: agent.fallbackCredentialIds || [],
-    apiEndpoint: agent.apiEndpoint || null,
-    claudeSessionId: null,
-    messages: [],
-    createdAt: now,
-    lastActiveAt: now,
-    active: false,
-    sessionType: 'human' as const,
-    agentId,
-    plugins: agent.plugins || agent.tools || [],
-    heartbeatEnabled: agent.heartbeatEnabled || false,
-    heartbeatIntervalSec: agent.heartbeatIntervalSec || null,
+  const session = ensureAgentThreadSession(agentId, user)
+  if (!session) {
+    return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
   }
-
-  sessions[sessionId] = session as Record<string, unknown>
-  saveSessions(sessions)
-
-  agent.threadSessionId = sessionId
-  agent.updatedAt = Date.now()
-  saveAgents(agents)
-
   return NextResponse.json(session)
 }

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

@@ -56,24 +56,46 @@ export async function POST(req: Request) {
     id,
     name: body.name,
     description: body.description,
+    soul: body.soul || undefined,
     systemPrompt: body.systemPrompt,
     provider: body.provider,
     model: body.model,
     credentialId: body.credentialId,
+    fallbackCredentialIds: body.fallbackCredentialIds,
     apiEndpoint: normalizeProviderEndpoint(body.provider, body.apiEndpoint || null),
+    gatewayProfileId: body.gatewayProfileId,
+    routingStrategy: body.routingStrategy,
+    routingTargets: body.routingTargets?.map((target) => ({
+      ...target,
+      apiEndpoint: normalizeProviderEndpoint(target.provider, target.apiEndpoint || null),
+    })),
     isOrchestrator: platformAssignScope === 'all',
     platformAssignScope,
     subAgentIds: body.subAgentIds,
     plugins: body.plugins?.length ? body.plugins : (body.tools || []),
+    skills: body.skills,
+    skillIds: body.skillIds,
+    mcpServerIds: body.mcpServerIds,
+    mcpDisabledTools: body.mcpDisabledTools?.length ? body.mcpDisabledTools : undefined,
     capabilities: body.capabilities,
     thinkingLevel: body.thinkingLevel || undefined,
     autoRecovery: body.autoRecovery || false,
+    heartbeatEnabled: body.heartbeatEnabled || false,
+    heartbeatInterval: body.heartbeatInterval,
+    heartbeatIntervalSec: body.heartbeatIntervalSec,
+    heartbeatModel: body.heartbeatModel,
+    heartbeatPrompt: body.heartbeatPrompt,
+    elevenLabsVoiceId: body.elevenLabsVoiceId,
     monthlyBudget: body.monthlyBudget ?? null,
     dailyBudget: body.dailyBudget ?? null,
     hourlyBudget: body.hourlyBudget ?? null,
     budgetAction: body.budgetAction || 'warn',
-    soul: body.soul || undefined,
     identityState: body.identityState ?? null,
+    memoryScopeMode: body.memoryScopeMode,
+    memoryTierPreference: body.memoryTierPreference,
+    projectId: body.projectId,
+    avatarSeed: body.avatarSeed,
+    avatarUrl: body.avatarUrl,
     sessionResetMode: body.sessionResetMode ?? null,
     sessionIdleTimeoutSec: body.sessionIdleTimeoutSec ?? null,
     sessionMaxAgeSec: body.sessionMaxAgeSec ?? null,

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

@@ -1,5 +1,5 @@
 import { NextResponse } from 'next/server'
-import { validateAccessKey, getAccessKey, isFirstTimeSetup, markSetupComplete } from '@/lib/server/storage'
+import { validateAccessKey, isFirstTimeSetup, markSetupComplete } from '@/lib/server/storage'
 import { ensureDaemonStarted } from '@/lib/server/daemon-state'
 import { AUTH_COOKIE_NAME, getCookieValue } from '@/lib/auth'
 export const dynamic = 'force-dynamic'

package/src/app/api/chatrooms/[id]/chat/route.ts

@@ -12,7 +12,8 @@ import {
   resolveAgentApiEndpoint,
   compactChatroomMessages,
   buildChatroomSystemPrompt,
-  buildSyntheticSession,
+  ensureSyntheticSession,
+  appendSyntheticSessionMessage,
   buildAgentSystemPromptForChatroom,
   buildHistoryForAgent,
   isMuted,
@@ -21,6 +22,7 @@ import { filterHealthyChatroomAgents } from '@/lib/server/chatroom-health'
 import { evaluateRoutingRules } from '@/lib/server/chatroom-routing'
 import { markProviderFailure, markProviderSuccess } from '@/lib/server/provider-health'
 import { applyAgentReactionsFromText } from '@/lib/server/chatroom-orchestration'
+import { resolvePrimaryAgentRoute } from '@/lib/server/agent-runtime-config'
 import type { Chatroom, ChatroomMessage, Agent } from '@/types'
 
 export const dynamic = 'force-dynamic'
@@ -150,9 +152,10 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
           }
 
           // Pre-flight: check if the agent's provider is usable before attempting to stream
-          const providerInfo = getProvider(agent.provider)
-          const apiKey = resolveApiKey(agent.credentialId)
-          const resolvedEndpoint = resolveAgentApiEndpoint(agent)
+          const route = resolvePrimaryAgentRoute(agent)
+          const providerInfo = getProvider(route?.provider || agent.provider)
+          const apiKey = resolveApiKey(route?.credentialId || agent.credentialId)
+          const resolvedEndpoint = route?.apiEndpoint || resolveAgentApiEndpoint(agent)
           if (providerInfo?.requiresApiKey && !apiKey) {
             writeEvent({ t: 'cr_agent_start', agentId: agent.id, agentName: agent.name })
             writeEvent({ t: 'err', text: `${agent.name} has no API credentials configured`, agentId: agent.id, agentName: agent.name })
@@ -177,7 +180,12 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
               notify(`chatroom:${id}`)
             }
 
-            const syntheticSession = buildSyntheticSession(agent, id)
+            const syntheticSession = ensureSyntheticSession(agent, id)
+            syntheticSession.provider = route?.provider || syntheticSession.provider
+            syntheticSession.model = route?.model || syntheticSession.model
+            syntheticSession.credentialId = route?.credentialId ?? syntheticSession.credentialId ?? null
+            syntheticSession.fallbackCredentialIds = route?.fallbackCredentialIds || syntheticSession.fallbackCredentialIds || []
+            syntheticSession.gatewayProfileId = route?.gatewayProfileId ?? syntheticSession.gatewayProfileId ?? null
             syntheticSession.apiEndpoint = resolvedEndpoint
             const agentSystemPrompt = buildAgentSystemPromptForChatroom(agent)
             const chatroomContext = buildChatroomSystemPrompt(freshChatroom, agents, agent.id)
@@ -186,6 +194,7 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
 
             // Use enriched context message for chained agents, or reply context + original text
             const messageForAgent = item.contextMessage || (replyContext + text)
+            appendSyntheticSessionMessage(syntheticSession.id, 'user', messageForAgent)
 
             let fullText = ''
             let agentError = ''
@@ -223,12 +232,14 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
 
             // Don't persist empty or error-only messages — they pollute chat history
             if (!responseText.trim() && agentError) {
+              appendSyntheticSessionMessage(syntheticSession.id, 'assistant', agentError)
               markProviderFailure(agent.provider, agentError)
               writeEvent({ t: 'cr_agent_done', agentId: agent.id, agentName: agent.name })
               return []
             }
 
             if (responseText.trim()) {
+              appendSyntheticSessionMessage(syntheticSession.id, 'assistant', responseText)
               const parsedMentions = parseMentions(responseText, agents, freshChatroom.agentIds)
               const chainedHealth = filterHealthyChatroomAgents(parsedMentions, agents)
               const newMentions = chainedHealth.healthyAgentIds

package/src/app/api/chatrooms/[id]/pins/route.ts

@@ -33,7 +33,8 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
   chatroom.updatedAt = Date.now()
   chatrooms[id] = chatroom
   saveChatrooms(chatrooms)
+  notify('chatrooms')
   notify(`chatroom:${id}`)
 
-  return NextResponse.json({ ok: true, pinnedMessageIds: chatroom.pinnedMessageIds })
+  return NextResponse.json(chatroom)
 }

package/src/app/api/chatrooms/[id]/reactions/route.ts

@@ -36,7 +36,8 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
   chatroom.updatedAt = Date.now()
   chatrooms[id] = chatroom
   saveChatrooms(chatrooms)
+  notify('chatrooms')
   notify(`chatroom:${id}`)
 
-  return NextResponse.json({ ok: true, reactions: message.reactions })
+  return NextResponse.json(chatroom)
 }

package/src/app/api/chatrooms/[id]/route.ts

@@ -33,6 +33,12 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
 
   // Diff agentIds and inject join/leave system messages
   if (Array.isArray(body.agentIds)) {
+    if (body.agentIds.length === 0) {
+      return NextResponse.json(
+        { error: 'Select at least one chatroom member.' },
+        { status: 400 },
+      )
+    }
     const agents = loadAgents()
     const invalidAgentIds = (body.agentIds as string[]).filter((agentId) => !agents[agentId])
     if (invalidAgentIds.length > 0) {

package/src/app/api/chats/[id]/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import { loadSessions, saveSessions, deleteSession, active, loadAgents } from '@/lib/server/storage'
 import { notFound } from '@/lib/server/collection-helpers'
 import { normalizeProviderEndpoint } from '@/lib/openclaw-endpoint'
+import { resolvePrimaryAgentRoute } from '@/lib/server/agent-runtime-config'
 
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
@@ -17,6 +18,7 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
   }
 
   const linkedAgent = nextAgentId ? loadAgents()[nextAgentId] : null
+  const linkedRoute = linkedAgent ? resolvePrimaryAgentRoute(linkedAgent) : null
 
   if (updates.name !== undefined) sessions[id].name = updates.name
   if (updates.cwd !== undefined) sessions[id].cwd = updates.cwd
@@ -24,11 +26,19 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
   else if (agentIdUpdateProvided && linkedAgent?.provider) sessions[id].provider = linkedAgent.provider
 
   if (updates.model !== undefined) sessions[id].model = updates.model
+  else if (agentIdUpdateProvided && linkedRoute?.model) sessions[id].model = linkedRoute.model
   else if (agentIdUpdateProvided && linkedAgent?.model !== undefined) sessions[id].model = linkedAgent.model
 
   if (updates.credentialId !== undefined) sessions[id].credentialId = updates.credentialId
+  else if (agentIdUpdateProvided && linkedRoute) sessions[id].credentialId = linkedRoute.credentialId ?? null
   else if (agentIdUpdateProvided && linkedAgent) sessions[id].credentialId = linkedAgent.credentialId ?? null
 
+  if (updates.fallbackCredentialIds !== undefined) sessions[id].fallbackCredentialIds = updates.fallbackCredentialIds
+  else if (agentIdUpdateProvided && linkedRoute) sessions[id].fallbackCredentialIds = [...linkedRoute.fallbackCredentialIds]
+
+  if (updates.gatewayProfileId !== undefined) sessions[id].gatewayProfileId = updates.gatewayProfileId
+  else if (agentIdUpdateProvided && linkedRoute) sessions[id].gatewayProfileId = linkedRoute.gatewayProfileId ?? null
+
   if (updates.plugins !== undefined) sessions[id].plugins = updates.plugins
   else if (agentIdUpdateProvided && linkedAgent) sessions[id].plugins = Array.isArray(linkedAgent.plugins) ? linkedAgent.plugins : []
 
@@ -37,6 +47,8 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
       updates.provider || sessions[id].provider,
       updates.apiEndpoint,
     )
+  } else if (agentIdUpdateProvided && linkedRoute) {
+    sessions[id].apiEndpoint = linkedRoute.apiEndpoint ?? null
   } else if (agentIdUpdateProvided && linkedAgent) {
     sessions[id].apiEndpoint = normalizeProviderEndpoint(
       linkedAgent.provider,

package/src/app/api/chats/heartbeat/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { DEFAULT_HEARTBEAT_INTERVAL_SEC } from '@/lib/heartbeat-defaults'
 import { disableAllSessionHeartbeats, loadSettings, saveSettings } from '@/lib/server/storage'
 import { cancelAllHeartbeatRuns } from '@/lib/server/session-run-manager'
 
@@ -11,7 +12,7 @@ export async function POST(req: Request) {
 
   const updatedSessions = disableAllSessionHeartbeats()
   const settings = loadSettings()
-  if ((settings.heartbeatIntervalSec ?? 120) !== 0) {
+  if ((settings.heartbeatIntervalSec ?? DEFAULT_HEARTBEAT_INTERVAL_SEC) !== 0) {
     settings.heartbeatIntervalSec = 0
     saveSettings(settings)
   }

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

@@ -7,6 +7,7 @@ import { WORKSPACE_DIR } from '@/lib/server/data-dir'
 import { notify } from '@/lib/server/ws-hub'
 import { getSessionRunState } from '@/lib/server/session-run-manager'
 import { normalizeProviderEndpoint } from '@/lib/openclaw-endpoint'
+import { applyResolvedRoute, resolvePrimaryAgentRoute } from '@/lib/server/agent-runtime-config'
 export const dynamic = 'force-dynamic'
 
 
@@ -60,6 +61,7 @@ export async function POST(req: Request) {
   const id = body.id || genId()
   const sessions = loadSessions()
   const agent = body.agentId ? loadAgents()[body.agentId] : null
+  const resolvedRoute = agent ? resolvePrimaryAgentRoute(agent) : null
   const requestedPlugins = Array.isArray(body.plugins) ? body.plugins : (Array.isArray(body.tools) ? body.tools : null)
   const resolvedPlugins = requestedPlugins ?? (Array.isArray(agent?.plugins) ? agent.plugins : (Array.isArray(agent?.tools) ? agent.tools : []))
 
@@ -70,12 +72,13 @@ export async function POST(req: Request) {
 
   const sessionName = body.name || 'New Chat'
 
-  sessions[id] = {
+  const nextSession = {
     id, name: sessionName, cwd,
     user: body.user || 'user',
     provider: body.provider || agent?.provider || 'claude-cli',
     model: body.model || agent?.model || '',
     credentialId: body.credentialId || agent?.credentialId || null,
+    fallbackCredentialIds: body.fallbackCredentialIds || agent?.fallbackCredentialIds || [],
     apiEndpoint: normalizeProviderEndpoint(
       body.provider || agent?.provider || 'claude-cli',
       body.apiEndpoint || agent?.apiEndpoint || null,
@@ -113,6 +116,9 @@ export async function POST(req: Request) {
     identityState: body.identityState ?? agent?.identityState ?? null,
     sessionArchiveState: body.sessionArchiveState ?? null,
   }
+  sessions[id] = (body.provider || body.model || body.credentialId || body.apiEndpoint)
+    ? nextSession
+    : applyResolvedRoute(nextSession, resolvedRoute)
   saveSessions(sessions)
   notify('sessions')
   return NextResponse.json(sessions[id])

package/src/app/api/external-agents/[id]/heartbeat/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from 'next/server'
+import { loadExternalAgents, saveExternalAgents } from '@/lib/server/storage'
+import { notFound } from '@/lib/server/collection-helpers'
+import { notify } from '@/lib/server/ws-hub'
+export const dynamic = 'force-dynamic'
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const body = await req.json().catch(() => ({}))
+  const items = loadExternalAgents()
+  const runtime = items[id]
+  if (!runtime) return notFound()
+  const now = Date.now()
+  runtime.lastHeartbeatAt = now
+  runtime.lastSeenAt = now
+  runtime.updatedAt = now
+  runtime.status = body.status || 'online'
+  if (body.tokenStats && typeof body.tokenStats === 'object') {
+    runtime.tokenStats = {
+      ...(runtime.tokenStats || {}),
+      ...body.tokenStats,
+    }
+  }
+  if (body.metadata && typeof body.metadata === 'object') {
+    runtime.metadata = {
+      ...(runtime.metadata || {}),
+      ...body.metadata,
+    }
+  }
+  saveExternalAgents(items)
+  notify('external_agents')
+  return NextResponse.json({ ok: true, id, lastHeartbeatAt: now })
+}