@swarmclawai/swarmclaw 1.5.60 → 1.5.61

package/README.md

@@ -399,6 +399,14 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.61 Highlights
+
+Adds an opt-in per-agent planning mode that rides on the existing `[MAIN_LOOP_PLAN]` token machinery.
+
+- **`Agent.planningMode: 'off' | 'strict' | null`** — new optional field on the Agent type. Defaults to `null` (off) so existing agents are unaffected. Validated by `AgentCreateSchema` / `AgentUpdateSchema` and surfaced through `createAgent` in `agent-service.ts`.
+- **Strict planning prompt section.** New `buildPlanningModeSection` in `prompt-sections.ts` injects a short contract into the system prompt when `planningMode === 'strict'`: before any multi-step work, emit a single-line `[MAIN_LOOP_PLAN]{"steps":...}` block. The existing parser in `main-agent-loop.ts` reads these blocks into `MainLoopState.planSteps` / `currentPlanStep` / `completedPlanSteps` with no additional wiring. Skipped in minimal prompt mode and for heartbeat turns.
+- **Test coverage.** `prompt-sections.planning-mode.test.ts` covers the null / off / strict / minimal / missing-agent paths (6 cases).
+
 ### v1.5.60 Highlights
 
 Adds a turn-snapshot primitive for external replay and comparison tooling, without touching the execution flow.
@@ -439,11 +447,6 @@ This release closes the org-orchestration feature gap with Paperclip while keepi
 - **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.
-- **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.
-
 Older releases: https://swarmclaw.ai/docs/release-notes
 
 - GitHub releases: https://github.com/swarmclawai/swarmclaw/releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.60",
+  "version": "1.5.61",
   "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/lib/server/agents/agent-service.ts

@@ -178,6 +178,7 @@ export function createAgent(input: {
     memoryTierPreference: (body.memoryTierPreference as Agent['memoryTierPreference']) || undefined,
     proactiveMemory: body.proactiveMemory !== false,
     autoDraftSkillSuggestions: body.autoDraftSkillSuggestions as Agent['autoDraftSkillSuggestions'],
+    planningMode: (body.planningMode as Agent['planningMode']) ?? null,
     projectId: typeof body.projectId === 'string' && body.projectId.trim() ? body.projectId.trim() : undefined,
     avatarSeed: typeof body.avatarSeed === 'string' ? body.avatarSeed : undefined,
     avatarUrl: typeof body.avatarUrl === 'string' ? body.avatarUrl : undefined,

package/src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { buildPlanningModeSection } from './prompt-sections'
+import type { Agent } from '@/types'
+
+function agentWith(partial: Partial<Agent>): Agent {
+  return {
+    id: 'test',
+    name: 'Test',
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-5',
+    credentialId: null,
+    apiEndpoint: null,
+    soul: null,
+    systemPrompt: null,
+    description: null,
+    tools: [],
+    extensions: [],
+    heartbeatEnabled: false,
+    delegationEnabled: false,
+    delegationTargetMode: 'all',
+    delegationTargetAgentIds: [],
+    skillIds: [],
+    createdAt: 0,
+    updatedAt: 0,
+    ...partial,
+  } as unknown as Agent
+}
+
+test('buildPlanningModeSection returns null when planningMode is undefined', () => {
+  const out = buildPlanningModeSection(agentWith({}), false)
+  assert.equal(out, null)
+})
+
+test('buildPlanningModeSection returns null when planningMode is "off"', () => {
+  const out = buildPlanningModeSection(agentWith({ planningMode: 'off' }), false)
+  assert.equal(out, null)
+})
+
+test('buildPlanningModeSection returns null when planningMode is null', () => {
+  const out = buildPlanningModeSection(agentWith({ planningMode: null }), false)
+  assert.equal(out, null)
+})
+
+test('buildPlanningModeSection returns null in minimal prompt mode', () => {
+  const out = buildPlanningModeSection(agentWith({ planningMode: 'strict' }), true)
+  assert.equal(out, null)
+})
+
+test('buildPlanningModeSection returns null when agent is missing', () => {
+  assert.equal(buildPlanningModeSection(null, false), null)
+  assert.equal(buildPlanningModeSection(undefined, false), null)
+})
+
+test('buildPlanningModeSection emits plan block guidance when strict', () => {
+  const out = buildPlanningModeSection(agentWith({ planningMode: 'strict' }), false)
+  assert.ok(out, 'should return a non-empty block')
+  assert.match(out!, /## Planning Mode: Strict/)
+  assert.match(out!, /\[MAIN_LOOP_PLAN\]/)
+  assert.match(out!, /"steps":/)
+  assert.match(out!, /current_step/)
+  assert.match(out!, /completed_steps/)
+})

package/src/lib/server/chat-execution/prompt-sections.ts

@@ -81,6 +81,42 @@ export function buildIdentitySection(
   return parts
 }
 
+// ---------------------------------------------------------------------------
+// Planning Mode — opt-in, per-agent
+// ---------------------------------------------------------------------------
+
+/**
+ * When `agent.planningMode === 'strict'`, inject a plan-enforcement section
+ * that tells the model to emit a [MAIN_LOOP_PLAN]{...} block before tool use
+ * on any multi-step turn. The existing main-agent-loop parser in
+ * `parseMainLoopPlan()` consumes these tokens and populates planSteps /
+ * currentPlanStep / completedPlanSteps in MainLoopState.
+ *
+ * Returns null when planning mode is off or minimal prompt mode is active.
+ */
+export function buildPlanningModeSection(
+  agent: Agent | null | undefined,
+  isMinimalPrompt: boolean,
+): string | null {
+  if (!agent || isMinimalPrompt) return null
+  if (agent.planningMode !== 'strict') return null
+  return [
+    '## Planning Mode: Strict',
+    '',
+    'Before any multi-step work (two or more tool calls or file edits), emit a single machine-readable plan block on its own line:',
+    '',
+    '```',
+    '[MAIN_LOOP_PLAN]{"steps":["step 1","step 2","step 3"],"current_step":"step 1","completed_steps":[]}',
+    '```',
+    '',
+    'Rules:',
+    '- Each step should be a short imperative phrase (≤80 chars).',
+    '- Update `current_step` as you advance, and append finished steps to `completed_steps`.',
+    '- Skip the block for trivial single-tool responses or pure Q&A.',
+    '- The block is parsed by the runtime; do not wrap it in prose, code fences, or extra punctuation.',
+  ].join('\n')
+}
+
 // ---------------------------------------------------------------------------
 // Thinking Level Guidance
 // ---------------------------------------------------------------------------

package/src/lib/server/chat-execution/stream-agent-chat.ts

@@ -17,6 +17,7 @@ import { loadRuntimeSettings, getAgentLoopRecursionLimit } from '@/lib/server/ru
 import { truncateToolResultText } from '@/lib/server/chat-execution/tool-result-guard'
 import {
   buildIdentitySection,
+  buildPlanningModeSection,
   buildThinkingSection,
   buildRuntimeOrientationSection,
   buildWorkspaceSection,
@@ -384,6 +385,8 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
   }
 
   // Composable prompt sections — each builder returns string | null (or string[])
+  const planningBlock = buildPlanningModeSection(sessionAgent, isMinimalPrompt)
+  if (planningBlock) promptParts.push(planningBlock)
   const thinkingBlock = buildThinkingSection(agentThinkingLevel, isMinimalPrompt)
   if (thinkingBlock) promptParts.push(thinkingBlock)
   const { rootSessionId } = resolveSessionLineageIds(session)

package/src/lib/validation/schemas.ts

@@ -122,6 +122,7 @@ export const AgentCreateSchema = z.object({
   memoryTierPreference: z.enum(['working', 'durable', 'archive', 'blended']).nullable().optional().default(null),
   proactiveMemory: z.boolean().optional().default(true),
   autoDraftSkillSuggestions: z.boolean().optional().default(true),
+  planningMode: z.enum(['off', 'strict']).nullable().optional().default(null),
   projectId: z.string().optional(),
   avatarSeed: z.string().optional(),
   avatarUrl: z.string().nullable().optional().default(null),

package/src/types/agent.ts

@@ -125,6 +125,14 @@ export interface Agent {
   proactiveMemory?: boolean
   /** Auto-refresh a reviewed skill draft from meaningful chat turns for this agent. */
   autoDraftSkillSuggestions?: boolean
+  /**
+   * Planning enforcement mode.
+   * - 'off' (default): no extra planning guidance
+   * - 'strict': instruct the model to emit a [MAIN_LOOP_PLAN] block before any
+   *   tool call on multi-step turns. The existing main-agent-loop plan parser
+   *   reads these blocks into MainLoopState.planSteps.
+   */
+  planningMode?: 'off' | 'strict' | null
   /** Controls whether file operations are confined to the workspace or allowed anywhere on the host. Default: 'workspace'. */
   filesystemScope?: 'workspace' | 'machine' | null
   /** Per-agent filesystem restrictions. Globs matched against resolved paths. */