@swarmclawai/swarmclaw 1.5.55 → 1.5.56

package/README.md

@@ -399,6 +399,11 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### 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.
+- **Zod-validated PUT/PATCH endpoints — hardening sweep.** Extends the v1.5.55 work (agents, tasks, webhooks) to close the same silent-corruption bug class on the remaining vulnerable routes: `PUT /api/secrets/:id`, `POST /api/secrets`, `PATCH /api/goals/:id`, `PUT /api/providers/:id`, `PUT /api/documents/:id`, `PUT /api/external-agents/:id`, and `PUT /api/chatrooms/:id`. Each route validates against a dedicated schema (`SecretUpdateSchema`, `SecretCreateSchema`, `GoalUpdateSchema`, `ProviderUpdateSchema`, `DocumentUpdateSchema`, `ExternalAgentUpdateSchema`, `ChatroomUpdateSchema`) in `src/lib/validation/schemas.ts`, then filters parsed data to the keys actually present in the raw body so Zod defaults can't overwrite untouched stored fields. Endpoints already doing per-field `typeof` guards (knowledge, gateways, projects) were left as-is.
+
 ### v1.5.55 Highlights
 
 - **Fix: mission budget updates with decimal values no longer silently fail with a 400.** The mission UI's `numOrNull` parsed user input with `Number.parseFloat`, but the API requires `int()` for `maxTokens`, `maxToolCalls`, `maxWallclockSec`, and `maxTurns`. Typing `1000.5` returned a cryptic Zod error to the toast and the update was lost. Added `intOrNull` (rounds) in `mission-edit-sheet.tsx`, `mission-template-install-dialog.tsx`, and `app/missions/page.tsx`. `maxUsd` still accepts decimals.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.55",
+  "version": "1.5.56",
   "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/[id]/route.ts

@@ -9,6 +9,7 @@ import {
   ensureChatroomRoutingGuidance,
   synthesizeRoutingGuidanceFromRules,
 } from '@/lib/server/chatrooms/chatroom-routing'
+import { ChatroomUpdateSchema, formatZodError } from '@/lib/validation/schemas'
 
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
@@ -25,14 +26,23 @@ export async function GET(_req: Request, { params }: { params: Promise<{ id: str
 
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const { data: body, error } = await safeParseBody<Record<string, unknown>>(req)
+  const { data: raw, error } = await safeParseBody<Record<string, unknown>>(req)
   if (error) return error
+  const parsed = ChatroomUpdateSchema.safeParse(raw)
+  if (!parsed.success) return NextResponse.json(formatZodError(parsed.error), { status: 400 })
+
+  const rawKeys = new Set(Object.keys(raw ?? {}))
+  const body: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(parsed.data)) {
+    if (rawKeys.has(key)) body[key] = value
+  }
+
   const chatrooms = loadChatrooms()
   const chatroom = chatrooms[id]
   if (!chatroom) return notFound()
 
-  if (body.name !== undefined) chatroom.name = body.name
-  if (body.description !== undefined) chatroom.description = body.description
+  if (body.name !== undefined) chatroom.name = body.name as string
+  if (body.description !== undefined) chatroom.description = body.description as string
   if (body.chatMode !== undefined) {
     chatroom.chatMode = body.chatMode === 'parallel' ? 'parallel' : 'sequential'
   }

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

@@ -1,11 +1,7 @@
 import { NextResponse } from 'next/server'
 import crypto from 'crypto'
 import { loadDocuments, saveDocuments, upsertDocumentRevision } from '@/lib/server/storage'
-
-function normalizeObject(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
-  return value as Record<string, unknown>
-}
+import { DocumentUpdateSchema, formatZodError } from '@/lib/validation/schemas'
 
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
@@ -17,13 +13,22 @@ export async function GET(_req: Request, { params }: { params: Promise<{ id: str
 
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const body = await req.json().catch(() => ({}))
+  const raw = await req.json().catch(() => null)
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return NextResponse.json({ error: 'Invalid or missing request body' }, { status: 400 })
+  }
+  const parsed = DocumentUpdateSchema.safeParse(raw)
+  if (!parsed.success) return NextResponse.json(formatZodError(parsed.error), { status: 400 })
+
+  const rawKeys = new Set(Object.keys(raw))
+  const body = parsed.data
+
   const docs = loadDocuments()
   const doc = docs[id]
   if (!doc) return NextResponse.json({ error: 'Document not found' }, { status: 404 })
 
   // Snapshot previous content as a revision before updating
-  if (body.content !== undefined && body.content !== doc.content) {
+  if (rawKeys.has('content') && body.content !== undefined && body.content !== doc.content) {
     const prevVersion = typeof doc.currentVersion === 'number' ? doc.currentVersion : 0
     const revisionId = crypto.randomBytes(8).toString('hex')
     upsertDocumentRevision(revisionId, {
@@ -32,18 +37,18 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
       version: prevVersion,
       content: doc.content,
       createdAt: Date.now(),
-      createdBy: typeof body.createdBy === 'string' ? body.createdBy : null,
+      createdBy: body.createdBy ?? null,
     })
     doc.currentVersion = prevVersion + 1
   }
 
-  if (body.title !== undefined) doc.title = body.title
-  if (body.fileName !== undefined) doc.fileName = body.fileName
-  if (body.sourcePath !== undefined) doc.sourcePath = body.sourcePath
-  if (body.content !== undefined) doc.content = body.content
-  if (body.method !== undefined) doc.method = body.method
-  if (body.metadata !== undefined) doc.metadata = normalizeObject(body.metadata)
-  doc.textLength = typeof body.textLength === 'number'
+  if (rawKeys.has('title') && body.title !== undefined) doc.title = body.title
+  if (rawKeys.has('fileName')) doc.fileName = body.fileName ?? null
+  if (rawKeys.has('sourcePath')) doc.sourcePath = body.sourcePath ?? null
+  if (rawKeys.has('content') && body.content !== undefined) doc.content = body.content
+  if (rawKeys.has('method') && body.method !== undefined) doc.method = body.method
+  if (rawKeys.has('metadata') && body.metadata !== undefined) doc.metadata = body.metadata
+  doc.textLength = rawKeys.has('textLength') && body.textLength !== undefined
     ? body.textLength
     : String(doc.content || '').length
   doc.updatedAt = Date.now()

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

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import { loadExternalAgents, saveExternalAgents } from '@/lib/server/storage'
 import { mutateItem, notFound, type CollectionOps } from '@/lib/server/collection-helpers'
 import { notify } from '@/lib/server/ws-hub'
+import { ExternalAgentUpdateSchema, formatZodError } from '@/lib/validation/schemas'
 export const dynamic = 'force-dynamic'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -9,12 +10,24 @@ const ops: CollectionOps<any> = { load: loadExternalAgents, save: saveExternalAg
 
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const body = await req.json().catch(() => ({}))
+  const raw = await req.json().catch(() => null)
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return NextResponse.json({ error: 'Invalid or missing request body' }, { status: 400 })
+  }
+  const parsed = ExternalAgentUpdateSchema.safeParse(raw)
+  if (!parsed.success) return NextResponse.json(formatZodError(parsed.error), { status: 400 })
+
+  const rawKeys = new Set(Object.keys(raw))
+  const body: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(parsed.data)) {
+    if (rawKeys.has(key)) body[key] = value
+  }
+
   const now = Date.now()
   const result = mutateItem(ops, id, (runtime) => {
     const action = typeof body.action === 'string' ? body.action : ''
     const nextMetadata = body.metadata && typeof body.metadata === 'object'
-      ? { ...(runtime.metadata || {}), ...body.metadata }
+      ? { ...(runtime.metadata || {}), ...(body.metadata as Record<string, unknown>) }
       : runtime.metadata
 
     const next = {

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

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 import { getGoalById, updateGoal, deleteGoal, getGoalChain } from '@/lib/server/goals/goal-service'
 import { notFound } from '@/lib/server/collection-helpers'
+import { GoalUpdateSchema, formatZodError } from '@/lib/validation/schemas'
 export const dynamic = 'force-dynamic'
 
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
@@ -14,9 +15,18 @@ export async function GET(_req: Request, { params }: { params: Promise<{ id: str
 
 export async function PATCH(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const { data: body, error } = await safeParseBody<Record<string, unknown>>(req)
+  const { data: raw, error } = await safeParseBody<Record<string, unknown>>(req)
   if (error) return error
-  const updated = updateGoal(id, body)
+  const parsed = GoalUpdateSchema.safeParse(raw)
+  if (!parsed.success) return NextResponse.json(formatZodError(parsed.error), { status: 400 })
+
+  const rawKeys = new Set(Object.keys(raw ?? {}))
+  const patch: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(parsed.data)) {
+    if (rawKeys.has(key)) patch[key] = value
+  }
+
+  const updated = updateGoal(id, patch)
   if (!updated) return notFound()
   return NextResponse.json(updated)
 }

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

@@ -4,6 +4,7 @@ import { loadProviderConfigs, saveProviderConfigs } from '@/lib/server/storage'
 import { mutateItem, deleteItem, notFound, badRequest, type CollectionOps } from '@/lib/server/collection-helpers'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 import { notify } from '@/lib/server/ws-hub'
+import { ProviderUpdateSchema, formatZodError } from '@/lib/validation/schemas'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const ops: CollectionOps<any> = { load: loadProviderConfigs, save: saveProviderConfigs, topic: 'providers' }
@@ -18,8 +19,17 @@ export async function GET(_req: Request, { params }: { params: Promise<{ id: str
 
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const { data: body, error } = await safeParseBody<Record<string, unknown>>(req)
+  const { data: raw, error } = await safeParseBody<Record<string, unknown>>(req)
   if (error) return error
+  const parsed = ProviderUpdateSchema.safeParse(raw)
+  if (!parsed.success) return NextResponse.json(formatZodError(parsed.error), { status: 400 })
+
+  const rawKeys = new Set(Object.keys(raw ?? {}))
+  const body: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(parsed.data)) {
+    if (rawKeys.has(key)) body[key] = value
+  }
+
   if (!ops.load()[id]) {
     const builtin = PROVIDERS[id]
     if (!builtin) return notFound()

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

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import { loadSecrets, saveSecrets } from '@/lib/server/storage'
 import { mutateItem, deleteItem, notFound, type CollectionOps } from '@/lib/server/collection-helpers'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
+import { SecretUpdateSchema, formatZodError } from '@/lib/validation/schemas'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const ops: CollectionOps<any> = { load: loadSecrets, save: saveSecrets }
@@ -25,14 +26,19 @@ export async function DELETE(_req: Request, { params }: { params: Promise<{ id:
 
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const { data: body, error } = await safeParseBody<Record<string, unknown>>(req)
+  const { data: raw, error } = await safeParseBody<Record<string, unknown>>(req)
   if (error) return error
+  const parsed = SecretUpdateSchema.safeParse(raw)
+  if (!parsed.success) return NextResponse.json(formatZodError(parsed.error), { status: 400 })
+  const rawKeys = new Set(Object.keys(raw ?? {}))
+  const body = parsed.data
+
   const result = mutateItem(ops, id, (secret) => {
-    if (body.name !== undefined) secret.name = body.name
-    if (body.service !== undefined) secret.service = body.service
-    if (body.scope !== undefined) secret.scope = body.scope
-    if (body.agentIds !== undefined) secret.agentIds = body.agentIds
-    if (body.projectId !== undefined) secret.projectId = body.projectId || undefined
+    if (rawKeys.has('name') && body.name !== undefined) secret.name = body.name
+    if (rawKeys.has('service') && body.service !== undefined) secret.service = body.service
+    if (rawKeys.has('scope') && body.scope !== undefined) secret.scope = body.scope
+    if (rawKeys.has('agentIds') && body.agentIds !== undefined) secret.agentIds = body.agentIds
+    if (rawKeys.has('projectId')) secret.projectId = body.projectId || undefined
     secret.updatedAt = Date.now()
     return secret
   })

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

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import { genId } from '@/lib/id'
 import { loadSecrets, saveSecrets, encryptKey } from '@/lib/server/storage'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
+import { SecretCreateSchema, formatZodError } from '@/lib/validation/schemas'
 export const dynamic = 'force-dynamic'
 
 
@@ -18,16 +19,20 @@ export async function GET(_req: Request) {
 }
 
 export async function POST(req: Request) {
-  const { data: body, error } = await safeParseBody<{ value?: string; name?: string; service?: string; scope?: string; agentIds?: string[]; projectId?: string }>(req)
+  const { data: raw, error } = await safeParseBody<Record<string, unknown>>(req)
   if (error) return error
-  const id = genId()
-  const now = Date.now()
-  const secrets = loadSecrets()
+  const parsed = SecretCreateSchema.safeParse(raw)
+  if (!parsed.success) return NextResponse.json(formatZodError(parsed.error), { status: 400 })
+  const body = parsed.data
 
-  if (!body.value?.trim()) {
+  if (!body.value.trim()) {
     return NextResponse.json({ error: 'value is required' }, { status: 400 })
   }
 
+  const id = genId()
+  const now = Date.now()
+  const secrets = loadSecrets()
+
   secrets[id] = {
     id,
     name: body.name || 'Unnamed Secret',

package/src/app/api/tts/route.test.ts

@@ -80,3 +80,53 @@ test('tts routes reject empty text with a validation error', () => {
   assert.equal(output.streamPayload.error, 'Validation failed')
   assert.deepEqual(output.streamPayload.issues, [{ path: 'text', message: 'No text provided' }])
 })
+
+test('tts routes return a JSON error when no ElevenLabs API key is configured', () => {
+  // Regression: both routes previously returned the raw error string via
+  // `new NextResponse(message, { status: 500 })`, which serialized to a
+  // `{"type":"Buffer","data":[...]}` blob on the CLI side because the response
+  // had no content-type. They must now return a proper JSON error body.
+  const output = runWithTempDataDir<{
+    ttsStatus: number
+    ttsContentType: string | null
+    ttsPayload: { error?: string }
+    streamStatus: number
+    streamContentType: string | null
+    streamPayload: { error?: string }
+  }>(`
+    delete process.env.ELEVENLABS_API_KEY
+    const ttsRouteMod = await import('./src/app/api/tts/route')
+    const ttsStreamRouteMod = await import('./src/app/api/tts/stream/route')
+    const ttsRoute = ttsRouteMod.default || ttsRouteMod
+    const ttsStreamRoute = ttsStreamRouteMod.default || ttsStreamRouteMod
+
+    const ttsResponse = await ttsRoute.POST(new Request('http://local/api/tts', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ text: 'hello' }),
+    }))
+
+    const ttsStreamResponse = await ttsStreamRoute.POST(new Request('http://local/api/tts/stream', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ text: 'hello' }),
+    }))
+
+    console.log(JSON.stringify({
+      ttsStatus: ttsResponse.status,
+      ttsContentType: ttsResponse.headers.get('content-type'),
+      ttsPayload: await ttsResponse.json(),
+      streamStatus: ttsStreamResponse.status,
+      streamContentType: ttsStreamResponse.headers.get('content-type'),
+      streamPayload: await ttsStreamResponse.json(),
+    }))
+  `, { prefix: 'swarmclaw-tts-route-' })
+
+  assert.equal(output.ttsStatus, 500)
+  assert.ok(output.ttsContentType?.includes('application/json'), `expected JSON content-type, got ${output.ttsContentType}`)
+  assert.match(output.ttsPayload.error ?? '', /ElevenLabs API key/i)
+
+  assert.equal(output.streamStatus, 500)
+  assert.ok(output.streamContentType?.includes('application/json'), `expected JSON content-type, got ${output.streamContentType}`)
+  assert.match(output.streamPayload.error ?? '', /ElevenLabs API key/i)
+})

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

@@ -23,6 +23,9 @@ export async function POST(req: Request) {
       },
     })
   } catch (err: unknown) {
-    return new NextResponse(explainElevenLabsError(err), { status: 500 })
+    return NextResponse.json(
+      { error: explainElevenLabsError(err) },
+      { status: 500 },
+    )
   }
 }

package/src/app/api/tts/stream/route.ts

@@ -1,3 +1,4 @@
+import { NextResponse } from 'next/server'
 import { z } from 'zod'
 
 import { explainElevenLabsError, requestElevenLabsMp3Stream } from '@/lib/server/elevenlabs'
@@ -22,6 +23,9 @@ export async function POST(req: Request) {
       },
     })
   } catch (err: unknown) {
-    return new Response(explainElevenLabsError(err), { status: 500 })
+    return NextResponse.json(
+      { error: explainElevenLabsError(err) },
+      { status: 500 },
+    )
   }
 }

package/src/lib/validation/schemas.test.ts

@@ -58,6 +58,22 @@ describe('AgentCreateSchema', () => {
     assert.equal(parsed.sessionResetMode, 'isolated')
   })
 
+  it('preserves heartbeat goal/nextAction/target/prompt fields without dropping them', () => {
+    const parsed = AgentCreateSchema.parse({
+      name: 'Daily Reporter',
+      provider: 'openai',
+      heartbeatPrompt: 'Custom prompt',
+      heartbeatGoal: 'Report the day-of-week',
+      heartbeatNextAction: 'Reply with weekday',
+      heartbeatTarget: 'last',
+    })
+
+    assert.equal(parsed.heartbeatPrompt, 'Custom prompt')
+    assert.equal(parsed.heartbeatGoal, 'Report the day-of-week')
+    assert.equal(parsed.heartbeatNextAction, 'Reply with weekday')
+    assert.equal(parsed.heartbeatTarget, 'last')
+  })
+
   it('accepts executeConfig for sandboxed execute defaults', () => {
     const parsed = AgentCreateSchema.parse({
       name: 'Builder',

package/src/lib/validation/schemas.ts

@@ -104,6 +104,9 @@ export const AgentCreateSchema = z.object({
   heartbeatIntervalSec: z.number().int().nonnegative().nullable().optional().default(null),
   heartbeatModel: z.string().nullable().optional().default(null),
   heartbeatPrompt: z.string().nullable().optional().default(null),
+  heartbeatGoal: z.string().nullable().optional().default(null),
+  heartbeatNextAction: z.string().nullable().optional().default(null),
+  heartbeatTarget: z.string().nullable().optional().default(null),
   orchestratorEnabled: z.boolean().optional().default(false),
   orchestratorMission: z.string().optional().default(''),
   orchestratorWakeInterval: z.union([z.string(), z.number()]).nullable().optional().default(null),
@@ -237,6 +240,95 @@ export const WebhookUpdateSchema = z.object({
   isEnabled: z.boolean().optional(),
 })
 
+/** PUT /secrets/:id body. Never allow mutating `encryptedValue` here — that only
+ * happens via POST /secrets with a fresh plaintext value that we re-encrypt. */
+export const SecretUpdateSchema = z.object({
+  name: z.string().min(1).max(200).optional(),
+  service: z.string().max(64).optional(),
+  scope: z.enum(['global', 'agent', 'project']).optional(),
+  agentIds: z.array(z.string()).max(64).optional(),
+  projectId: z.string().nullable().optional(),
+}).strict()
+
+export const SecretCreateSchema = z.object({
+  value: z.string().min(1, 'value is required'),
+  name: z.string().max(200).optional(),
+  service: z.string().max(64).optional(),
+  scope: z.enum(['global', 'agent', 'project']).optional(),
+  agentIds: z.array(z.string()).max(64).optional(),
+  projectId: z.string().nullable().optional(),
+}).strict()
+
+/** PATCH /goals/:id — partial updates of a Goal. Matches the Goal type. */
+export const GoalUpdateSchema = z.object({
+  title: z.string().min(1).max(200).optional(),
+  description: z.string().max(4000).optional(),
+  level: z.enum(['organization', 'team', 'project', 'agent', 'task']).optional(),
+  parentGoalId: z.string().nullable().optional(),
+  projectId: z.string().nullable().optional(),
+  agentId: z.string().nullable().optional(),
+  taskId: z.string().nullable().optional(),
+  objective: z.string().max(4000).optional(),
+  constraints: z.array(z.string()).max(32).optional(),
+  successMetric: z.string().max(1000).nullable().optional(),
+  budgetUsd: z.number().nonnegative().nullable().optional(),
+  deadlineAt: z.number().nullable().optional(),
+  status: z.enum(['active', 'achieved', 'abandoned']).optional(),
+}).strict()
+
+/** PUT /providers/:id — any of the provider-config writable fields. */
+export const ProviderUpdateSchema = z.object({
+  name: z.string().min(1).max(200).optional(),
+  baseUrl: z.string().optional(),
+  models: z.array(z.string()).max(200).optional(),
+  credentialId: z.string().nullable().optional(),
+  isEnabled: z.boolean().optional(),
+  requiresApiKey: z.boolean().optional(),
+  notes: z.string().max(4000).nullable().optional(),
+}).strict()
+
+/** PUT /documents/:id — note: creating a new revision is a side-effect of
+ * passing a new `content`, so content shape is strict here. */
+export const DocumentUpdateSchema = z.object({
+  title: z.string().min(1).max(500).optional(),
+  fileName: z.string().max(500).nullable().optional(),
+  sourcePath: z.string().max(4000).nullable().optional(),
+  content: z.string().optional(),
+  method: z.string().max(64).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  textLength: z.number().int().nonnegative().optional(),
+  createdBy: z.string().max(200).nullable().optional(),
+}).strict()
+
+/** PUT /external-agents/:id — runtime fields + `action` control. */
+export const ExternalAgentUpdateSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().min(1).max(200).optional(),
+  sourceType: z.enum(['codex', 'claude', 'opencode', 'openclaw', 'custom', 'a2a']).optional(),
+  status: z.enum(['online', 'idle', 'offline', 'stale']).optional(),
+  provider: z.string().nullable().optional(),
+  model: z.string().nullable().optional(),
+  workspace: z.string().nullable().optional(),
+  transport: z.enum(['http', 'ws', 'cli', 'gateway', 'custom']).nullable().optional(),
+  endpoint: z.string().nullable().optional(),
+  agentId: z.string().nullable().optional(),
+  gatewayProfileId: z.string().nullable().optional(),
+  capabilities: z.array(z.string()).optional(),
+  labels: z.array(z.string()).optional(),
+  lifecycleState: z.enum(['active', 'draining', 'cordoned']).optional(),
+  gatewayTags: z.array(z.string()).optional(),
+  gatewayUseCase: z.string().nullable().optional(),
+  version: z.string().nullable().optional(),
+  lastHealthNote: z.string().nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).nullable().optional(),
+  action: z.enum(['activate', 'drain', 'cordon', 'restart']).optional(),
+  tokenStats: z.object({
+    inputTokens: z.number().nonnegative().optional(),
+    outputTokens: z.number().nonnegative().optional(),
+    totalTokens: z.number().nonnegative().optional(),
+  }).nullable().optional(),
+})
+
 export const ChatroomCreateSchema = z.object({
   name: z.string().min(1, 'Chatroom name is required'),
   agentIds: z.array(z.string()).min(1, 'Select at least one agent').default([]),
@@ -254,6 +346,11 @@ export const ChatroomCreateSchema = z.object({
   })).optional(),
 })
 
+/** PUT /chatrooms/:id — partial updates. `agentIds` and moderation flows have
+ * their own downstream validation in the route, so this schema just guards
+ * types and ranges. */
+export const ChatroomUpdateSchema = ChatroomCreateSchema.partial()
+
 export const ProtocolPhaseDefinitionSchema = z.object({
   id: z.string().min(1),
   kind: z.enum([