@swarmclawai/swarmclaw 1.5.59 → 1.5.61

package/README.md

@@ -399,6 +399,21 @@ 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.
+
+- **Turn snapshot endpoint.** New `GET /api/chats/:id/turns/:index/snapshot` returns the input state of a prior user turn: the message (text + optional imagePath + time), all prior messages in order, the session's effective provider/model/endpoint/credential at snapshot time, and the bound agent's provider/model/systemPrompt when available. Invalid or non-user indices return `400`, out-of-range indices return `404`. CLI: `swarmclaw chats turn-snapshot <chatId> <index>`.
+- **Use case.** External CLIs, notebooks, and comparison harnesses can now capture the exact inputs that produced a given turn and replay them against a different model, provider, or system prompt to compare outputs — without mutating the original session. Pairs with the existing `edit-resend` path (destructive in-session replay) and the new share-link infrastructure in v1.5.59 (share the original turn's context, replay on another instance).
+
 ### v1.5.59 Highlights
 
 Viral-loop release. Adds public share links for missions, skills, and sessions, plus a complementary raw-markdown endpoint so any shared skill installs directly through the existing `POST /api/skills/import`.
@@ -432,21 +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.
-
-### 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.
-- **Fix: mission edit sheet's connectors dropdown was always empty.** The sheet fetched `/connectors` expecting a `Connector[]`, but the endpoint returns `Record<string, Connector>`. The defensive `Array.isArray` fallback quietly rendered an empty list, so users could not attach report connectors when editing a running mission. Now typed as `Record<string, Connector>` and projected with `Object.values`.
-- **Fix: memory search returns results for short (3-4 char) words like `cats`, `blue`, `dog`.** `buildFtsQuery` had a `unique[0].length >= 5` guard that returned an empty FTS query for any single-token search shorter than 5 chars, silently dropping valid searches. The upstream filter already requires ≥3 chars, so the extra guard just excluded useful queries. Removed; regression tests cover `cats`, `blue`, and `dog`.
-- **Fix: `PUT /api/agents/:id` now validates its body with a Zod schema.** Previously the route did `{...current, ...body}` without validation, so sending `{"tools": "not_an_array"}` silently wiped the agent's tool list to `[]`. Added `AgentUpdateSchema = AgentCreateSchema.partial()` and a filter step that keeps only keys present in the raw body (so Zod defaults do not overwrite untouched fields). Bad types now return a 400 with field-level errors. `updateAgent()` keeps a `current.tools` / `current.extensions` fallback as defense-in-depth for internal callers.
-- **Fix: `PUT /api/tasks/:id` now validates its body with a Zod schema.** Same class of bug: a numeric `title` silently corrupted the stored field. Added `TaskUpdateSchema = TaskCreateSchema.partial().extend({...})` with the update-only fields (`appendComment`, `result`, `error`, lifecycle timestamps) and the same raw-key filter pattern. Bad types now 400 with untouched storage.
-- **Fix: `PUT /api/webhooks/:id` now validates its body with a Zod schema.** Previously `{"events": "not_an_array"}` wiped the events list. Added `WebhookUpdateSchema` and explicit `rawKeys.has(...)` guards in the mutate closure so only fields actually present in the body are applied.
-- **Fix: classifier JSON no longer leaks into assistant responses.** Some Ollama / Ollama Cloud turns were emitting the internal `MessageClassification` object directly into the stream (e.g. `{"taskIntent":"research",...}` prepended to the real reply). The existing stripper only matched when `isDeliverableTask` was the first key, so leaks starting with `taskIntent` sailed through to the user. Replaced the regex with a principled detector that brace-matches candidate JSON (string-quote aware) and validates against `MessageClassificationSchema.safeParse` — the schema itself is the source of truth, so future schema changes can't break detection.
-
 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.59",
+  "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/app/api/chats/[id]/turns/[index]/snapshot/route.ts

@@ -0,0 +1,90 @@
+import { NextResponse } from 'next/server'
+import { getSession } from '@/lib/server/sessions/session-repository'
+import { getMessages } from '@/lib/server/messages/message-repository'
+import { loadAgent } from '@/lib/server/agents/agent-repository'
+
+export const dynamic = 'force-dynamic'
+
+/**
+ * Turn snapshot — returns the input state of the turn at :index so external
+ * tools (CLIs, notebooks, comparison harnesses) can replay the same turn
+ * against a different model, provider, or system prompt without mutating
+ * the original session.
+ *
+ * Shape is intentionally minimal and stable:
+ *  - `userMessage`: the message that opened the turn (text + optional imagePath)
+ *  - `priorMessages`: everything before that turn, in order
+ *  - `route`: the session's effective provider/model/endpoint at snapshot time
+ *  - `agent`: the agent's provider/model/systemPrompt (if bound), for reference
+ */
+export async function GET(
+  _req: Request,
+  ctx: { params: Promise<{ id: string; index: string }> },
+) {
+  const { id, index } = await ctx.params
+  const session = getSession(id)
+  if (!session) {
+    return NextResponse.json({ error: 'session_not_found' }, { status: 404 })
+  }
+
+  const i = Number.parseInt(index, 10)
+  if (!Number.isInteger(i) || i < 0) {
+    return NextResponse.json({ error: 'invalid_index' }, { status: 400 })
+  }
+
+  const messages = getMessages(id)
+  if (i >= messages.length) {
+    return NextResponse.json({ error: 'index_out_of_range' }, { status: 404 })
+  }
+
+  const target = messages[i]
+  if (!target || target.role !== 'user') {
+    return NextResponse.json({ error: 'not_a_user_turn' }, { status: 400 })
+  }
+
+  const priorMessages = messages.slice(0, i).map((m) => ({
+    role: m.role,
+    text: m.text || '',
+    at: typeof m.time === 'number' ? m.time : null,
+  }))
+
+  const userMessage = {
+    text: target.text || '',
+    imagePath: target.imagePath || null,
+    at: typeof target.time === 'number' ? target.time : null,
+  }
+
+  const route = {
+    provider: session.provider ?? null,
+    model: session.model ?? null,
+    apiEndpoint: session.apiEndpoint ?? null,
+    credentialId: session.credentialId ?? null,
+  }
+
+  let agent: null | {
+    id: string
+    provider: string | null
+    model: string | null
+    systemPrompt: string | null
+  } = null
+  if (session.agentId) {
+    const a = loadAgent(session.agentId)
+    if (a) {
+      agent = {
+        id: a.id,
+        provider: (a.provider as string) ?? null,
+        model: (a.model as string) ?? null,
+        systemPrompt: typeof a.systemPrompt === 'string' ? a.systemPrompt : null,
+      }
+    }
+  }
+
+  return NextResponse.json({
+    sessionId: id,
+    index: i,
+    userMessage,
+    priorMessages,
+    route,
+    agent,
+  })
+}

package/src/cli/index.js

@@ -579,6 +579,7 @@ const COMMAND_GROUPS = [
       cmd('messages-send', 'POST', '/chats/:id/messages', 'Append a user/system message to a chat', { expectsJsonBody: true }),
       cmd('messages-delete', 'DELETE', '/chats/:id/messages', 'Delete a message from a chat', { expectsJsonBody: true }),
       cmd('edit-resend', 'POST', '/chats/:id/edit-resend', 'Edit and resend from a specific message index', { expectsJsonBody: true }),
+      cmd('turn-snapshot', 'GET', '/chats/:id/turns/:index/snapshot', 'Snapshot the input state of a prior user turn (for external replay)'),
       cmd('chat', 'POST', '/chats/:id/chat', 'Send chat message (streaming)', {
         expectsJsonBody: true,
         responseType: 'sse',

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. */