@swarmclawai/swarmclaw 1.9.15 → 1.9.16

package/README.md

@@ -399,6 +399,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.16 Highlights
+
+Agent planning controls release: strict planning is now a first-class agent setting instead of a hidden persisted field, so operators can decide which agents must expose machine-readable plans before multi-step work.
+
+- **Agent editor control.** Advanced agent settings now include a Standard / Strict planning selector with inline behavior guidance.
+- **Runtime prompt wiring.** Strict planning continues to inject the existing `[MAIN_LOOP_PLAN]` contract before multi-step tool work, and the test suite now keeps that prompt section in the runtime gate.
+- **Portable agent packs.** Agent exports preserve `planningMode`, so planning discipline follows agents across installs.
+- **API coverage.** Agent create and update route tests verify that strict planning persists without clobbering unrelated settings.
+
 ### v1.9.15 Highlights
 
 Run handoff release: SwarmClaw now turns completed, failed, queued, or running execution records into copyable handoff packets with outcome, evidence, artifacts, timeline, usage, resume commands, and recommended next actions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.15",
+  "version": "1.9.16",
   "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",
@@ -88,7 +88,7 @@
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/ensure-sandbox-browser-image.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/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/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/gateways/gateway-topology.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/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/gateways/topology-route.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
-    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/chats/session-context-pack.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/runs/run-handoff.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/quality/release-readiness.test.ts src/lib/quality/architecture-health.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-execution-policy.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/runs/run-handoff-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
+    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/agent-planning-mode.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/chats/session-context-pack.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/runs/run-handoff.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/quality/release-readiness.test.ts src/lib/quality/architecture-health.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-execution-policy.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/runs/run-handoff-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",
     "test:e2e": "node --import tsx scripts/browser-e2e-smoke.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",

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

@@ -101,6 +101,27 @@ test('POST /api/agents accepts a valid provider and creates the agent', async ()
   saveAgents(agents)
 })
 
+test('POST /api/agents persists strict planning mode for created agents', async () => {
+  const response = await createAgent(new Request('http://local/api/agents', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      name: 'Planning Agent',
+      provider: 'ollama',
+      model: 'qwen3.5',
+      planningMode: 'strict',
+    }),
+  }))
+
+  assert.equal(response.status, 200)
+  const body = await response.json()
+  assert.equal(body.planningMode, 'strict')
+
+  const agents = loadAgents()
+  delete agents[body.id]
+  saveAgents(agents)
+})
+
 test('POST /api/agents rejects missing required fields with a 400', async () => {
   const response = await createAgent(new Request('http://local/api/agents', {
     method: 'POST',
@@ -163,6 +184,28 @@ test('PUT /api/agents/:id does not clobber untouched fields with schema defaults
   assert.equal(body.proactiveMemory, false)
 })
 
+test('PUT /api/agents/:id updates planning mode without clobbering other fields', async () => {
+  seedAgent('agent-planning-mode', {
+    name: 'Planner',
+    tools: ['memory'],
+    planningMode: 'off',
+    proactiveMemory: false,
+  })
+
+  const response = await putAgent(new Request('http://local/api/agents/agent-planning-mode', {
+    method: 'PUT',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ planningMode: 'strict' }),
+  }), routeParams('agent-planning-mode'))
+
+  assert.equal(response.status, 200)
+  const body = await response.json()
+  assert.equal(body.planningMode, 'strict')
+  assert.equal(body.name, 'Planner')
+  assert.deepEqual(body.tools, ['memory'])
+  assert.equal(body.proactiveMemory, false)
+})
+
 test('PUT /api/agents/:id rejects non-string name', async () => {
   seedAgent('agent-bad-name', { name: 'Good' })
 

package/src/components/agents/agent-sheet.tsx

@@ -26,6 +26,7 @@ import { StatusDot } from '@/components/ui/status-dot'
 import { resolveStoredOllamaMode } from '@/lib/ollama-mode'
 import { errorMessage } from '@/lib/shared-utils'
 import { getDefaultAgentToolIds } from '@/lib/agent-default-tools'
+import { AGENT_PLANNING_MODE_OPTIONS, describeAgentPlanningMode, normalizeAgentPlanningMode, type AgentPlanningMode } from '@/lib/agent-planning-mode'
 import { getEnabledExtensionIds, getEnabledToolIds } from '@/lib/capability-selection'
 import { buildAgentSelectableProviders, resolveAgentSelectableProviderCredentials } from '@/lib/agent-provider-options'
 import { AgentSocialSettings } from '@/features/swarmfeed/agent-social-settings'
@@ -238,6 +239,7 @@ export function AgentSheet() {
   const [memoryTierPreference, setMemoryTierPreference] = useState<'working' | 'durable' | 'archive' | 'blended'>('blended')
   const [proactiveMemory, setProactiveMemory] = useState(true)
   const [autoDraftSkillSuggestions, setAutoDraftSkillSuggestions] = useState(true)
+  const [planningMode, setPlanningMode] = useState<AgentPlanningMode>('off')
   const [autoRecovery, setAutoRecovery] = useState(false)
   const [disabled, setDisabled] = useState(false)
   const [filesystemScope, setFilesystemScope] = useState<'workspace' | 'machine'>('workspace')
@@ -444,6 +446,7 @@ export function AgentSheet() {
         setMemoryTierPreference(editing.memoryTierPreference || 'blended')
         setProactiveMemory(editing.proactiveMemory !== false)
         setAutoDraftSkillSuggestions(editing.autoDraftSkillSuggestions !== false)
+        setPlanningMode(normalizeAgentPlanningMode(editing.planningMode))
         setAutoRecovery(editing.autoRecovery || false)
         setDisabled(editing.disabled === true)
         setFilesystemScope(editing.filesystemScope === 'machine' ? 'machine' : 'workspace')
@@ -527,6 +530,7 @@ export function AgentSheet() {
         setMemoryTierPreference(src.memoryTierPreference || 'blended')
         setProactiveMemory(src.proactiveMemory !== false)
         setAutoDraftSkillSuggestions(src.autoDraftSkillSuggestions !== false)
+        setPlanningMode(normalizeAgentPlanningMode(src.planningMode))
         setAutoRecovery(src.autoRecovery || false)
         setDisabled(false)
         setFilesystemScope(src.filesystemScope === 'machine' ? 'machine' : 'workspace')
@@ -602,6 +606,7 @@ export function AgentSheet() {
         setMemoryTierPreference('blended')
         setProactiveMemory(true)
         setAutoDraftSkillSuggestions(true)
+        setPlanningMode('off')
         setAutoRecovery(false)
         setDisabled(false)
         setVoiceId('')
@@ -809,6 +814,7 @@ export function AgentSheet() {
       memoryTierPreference,
       proactiveMemory,
       autoDraftSkillSuggestions,
+      planningMode,
       autoRecovery,
       disabled,
       filesystemScope: filesystemScope === 'machine' ? 'machine' as const : undefined,
@@ -916,6 +922,7 @@ export function AgentSheet() {
         extensions: getEnabledExtensionIds(editing),
         capabilities: editing.capabilities,
         elevenLabsVoiceId: editing.elevenLabsVoiceId || null,
+        planningMode: normalizeAgentPlanningMode(editing.planningMode),
         soul: editing.soul,
         systemPrompt: editing.systemPrompt,
       }],
@@ -1043,6 +1050,7 @@ export function AgentSheet() {
     if (projectId) badges.push('Project')
     if (thinkingLevel) badges.push('Thinking')
     if (!autoDraftSkillSuggestions) badges.push('Skill drafting')
+    if (planningMode === 'strict') badges.push('Planning')
     return Array.from(new Set(badges))
   }, [
     autoDraftSkillSuggestions,
@@ -1061,6 +1069,7 @@ export function AgentSheet() {
     memoryScopeMode,
     memoryTierPreference,
     proactiveMemory,
+    planningMode,
     projectId,
     routingStrategy,
     routingTargets.length,
@@ -2145,7 +2154,15 @@ export function AgentSheet() {
           <option value="durable">Durable memory</option>
           <option value="archive">Archive memory</option>
         </select>
+        <select value={planningMode} onChange={(e) => setPlanningMode(normalizeAgentPlanningMode(e.target.value))} className={inputClass}>
+          {AGENT_PLANNING_MODE_OPTIONS.map((option) => (
+            <option key={option.value} value={option.value}>{option.label}</option>
+          ))}
+        </select>
       </div>
+      <p className="mb-4 text-[12px] leading-[1.6] text-text-3/70">
+        {describeAgentPlanningMode(planningMode)}
+      </p>
       <div className="space-y-3">
         <label className="flex items-center gap-3 cursor-pointer">
           <div

package/src/lib/agent-planning-mode.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import {
+  AGENT_PLANNING_MODE_OPTIONS,
+  describeAgentPlanningMode,
+  isAgentPlanningModeEnabled,
+  normalizeAgentPlanningMode,
+} from './agent-planning-mode'
+
+test('normalizeAgentPlanningMode accepts only supported persisted values', () => {
+  assert.equal(normalizeAgentPlanningMode('strict'), 'strict')
+  assert.equal(normalizeAgentPlanningMode('off'), 'off')
+  assert.equal(normalizeAgentPlanningMode(null), 'off')
+  assert.equal(normalizeAgentPlanningMode(undefined), 'off')
+  assert.equal(normalizeAgentPlanningMode('unexpected'), 'off')
+})
+
+test('planning mode options include a safe default and strict mode', () => {
+  assert.deepEqual(
+    AGENT_PLANNING_MODE_OPTIONS.map((option) => option.value),
+    ['off', 'strict'],
+  )
+  assert.equal(isAgentPlanningModeEnabled('strict'), true)
+  assert.equal(isAgentPlanningModeEnabled('off'), false)
+  assert.equal(isAgentPlanningModeEnabled(null), false)
+})
+
+test('describeAgentPlanningMode returns operator-facing copy for each mode', () => {
+  assert.match(describeAgentPlanningMode('off'), /No extra plan contract/)
+  assert.match(describeAgentPlanningMode('strict'), /machine-readable plan block/)
+})

package/src/lib/agent-planning-mode.ts

@@ -0,0 +1,34 @@
+import type { Agent } from '@/types'
+
+export type AgentPlanningMode = NonNullable<Agent['planningMode']>
+
+export const AGENT_PLANNING_MODE_OPTIONS: ReadonlyArray<{
+  value: AgentPlanningMode
+  label: string
+  description: string
+}> = [
+  {
+    value: 'off',
+    label: 'Standard',
+    description: 'No extra plan contract. The agent can answer, plan, or act normally based on the task.',
+  },
+  {
+    value: 'strict',
+    label: 'Strict planning',
+    description: 'Require a machine-readable plan block before multi-step tool work so progress can be tracked.',
+  },
+]
+
+export function normalizeAgentPlanningMode(value: unknown): AgentPlanningMode {
+  return value === 'strict' ? 'strict' : 'off'
+}
+
+export function isAgentPlanningModeEnabled(value: Agent['planningMode'] | undefined): boolean {
+  return normalizeAgentPlanningMode(value) === 'strict'
+}
+
+export function describeAgentPlanningMode(value: Agent['planningMode'] | undefined): string {
+  const mode = normalizeAgentPlanningMode(value)
+  return AGENT_PLANNING_MODE_OPTIONS.find((option) => option.value === mode)?.description
+    || AGENT_PLANNING_MODE_OPTIONS[0].description
+}

package/src/types/agent.ts

@@ -301,6 +301,7 @@ export interface AgentPackEntry {
   extensions?: string[]
   capabilities?: string[]
   elevenLabsVoiceId?: string | null
+  planningMode?: 'off' | 'strict' | null
   soul?: string
   systemPrompt?: string
 }