@swarmclawai/swarmclaw 0.7.4 → 0.7.5

package/README.md

@@ -117,7 +117,7 @@ curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.
 ```
 
 The installer resolves the latest stable release tag and installs that version by default.
-To pin a version: `SWARMCLAW_VERSION=v0.7.4 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v0.7.5 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -670,7 +670,7 @@ npm run update:easy     # safe update helper for local installs
 SwarmClaw uses tag-based releases (`vX.Y.Z`) as the stable channel.
 
 ```bash
-# example patch release (v0.7.4 style)
+# example patch release (v0.7.5 style)
 npm version patch
 git push origin main --follow-tags
 ```
@@ -680,13 +680,13 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.7.4 Release Readiness Notes
+#### v0.7.5 Release Readiness Notes
 
-Before shipping `v0.7.4`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.7.5`, confirm the following user-facing changes are reflected in docs:
 
 1. Sandbox docs are updated everywhere to reflect the current Deno-only `sandbox_exec` behavior and the guidance to prefer `http_request` for simple API calls.
 2. OpenClaw docs cover the current gateway/runtime behavior, including per-agent gateway routing, control-plane actions, and inspector-side advanced controls.
-3. Site and README install/version strings are updated to `v0.7.4`, including install snippets, release notes index text, and sidebar/footer labels.
+3. Site and README install/version strings are updated to `v0.7.5`, including install snippets, release notes index text, and sidebar/footer labels.
 4. Release notes summarize the user-visible setup/auth/runtime changes from the current worktree, especially gateway/external-agent/setup flow improvements.
 5. CLI and tool docs do not reference removed or non-functional surfaces such as the old `openclaw_sandbox` bridge.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.7.4",
+  "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": {

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

@@ -1,98 +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 { applyResolvedRoute, resolvePrimaryAgentRoute } from '@/lib/server/agent-runtime-config'
+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 baseSession = {
-    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 })
   }
-  const session = applyResolvedRoute(baseSession, resolvePrimaryAgentRoute(agent))
-
-  sessions[sessionId] = session as Record<string, unknown>
-  saveSessions(sessions)
-
-  agent.threadSessionId = sessionId
-  agent.updatedAt = Date.now()
-  saveAgents(agents)
-
   return NextResponse.json(session)
 }

package/src/lib/server/agent-thread-session.test.ts

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { describe, it } from 'node:test'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
+
+function runWithTempDataDir(script: string) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-agent-thread-'))
+  try {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DATA_DIR: path.join(tempDir, 'data'),
+        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
+        BROWSER_PROFILES_DIR: path.join(tempDir, 'browser-profiles'),
+      },
+      encoding: 'utf-8',
+    })
+    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+    const lines = (result.stdout || '')
+      .trim()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
+    return JSON.parse(jsonLine || '{}')
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}
+
+describe('ensureAgentThreadSession', () => {
+  it('creates and reuses an agent shortcut chat for heartbeat-enabled agents', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage.ts')
+      const storage = storageMod.default || storageMod['module.exports'] || storageMod
+      const helperMod = await import('./src/lib/server/agent-thread-session.ts')
+      const ensureAgentThreadSession = helperMod.ensureAgentThreadSession
+        || helperMod.default?.ensureAgentThreadSession
+        || helperMod['module.exports']?.ensureAgentThreadSession
+
+      const now = Date.now()
+      storage.saveAgents({
+        molly: {
+          id: 'molly',
+          name: 'Molly',
+          description: 'Autonomous helper',
+          provider: 'openai',
+          model: 'gpt-test',
+          credentialId: null,
+          apiEndpoint: null,
+          fallbackCredentialIds: [],
+          heartbeatEnabled: true,
+          heartbeatIntervalSec: 600,
+          createdAt: now,
+          updatedAt: now,
+          plugins: ['memory', 'web_search'],
+        },
+      })
+
+      const first = ensureAgentThreadSession('molly')
+      const second = ensureAgentThreadSession('molly')
+      const agents = storage.loadAgents()
+      const sessions = storage.loadSessions()
+
+      console.log(JSON.stringify({
+        firstId: first?.id,
+        secondId: second?.id,
+        threadSessionId: agents.molly?.threadSessionId || null,
+        session: first ? sessions[first.id] : null,
+      }))
+    `)
+
+    assert.equal(output.firstId, output.secondId)
+    assert.equal(output.threadSessionId, output.firstId)
+    assert.equal(output.session.shortcutForAgentId, 'molly')
+    assert.equal(output.session.agentId, 'molly')
+    assert.equal(output.session.heartbeatEnabled, true)
+    assert.deepEqual(output.session.plugins, ['memory', 'web_search'])
+  })
+})

package/src/lib/server/agent-thread-session.ts

@@ -0,0 +1,123 @@
+import { genId } from '@/lib/id'
+import type { Agent, Session } from '@/types'
+import { applyResolvedRoute, resolvePrimaryAgentRoute } from './agent-runtime-config'
+import { WORKSPACE_DIR } from './data-dir'
+import { loadAgents, loadSessions, saveAgents, saveSessions } from './storage'
+
+function buildEmptyDelegateResumeIds(): NonNullable<Session['delegateResumeIds']> {
+  return {
+    claudeCode: null,
+    codex: null,
+    opencode: null,
+    gemini: null,
+  }
+}
+
+function buildThreadSession(agent: Agent, sessionId: string, user: string, createdAt: number, existing?: Session): Session {
+  const baseSession: Session = {
+    id: sessionId,
+    name: agent.name,
+    shortcutForAgentId: agent.id,
+    cwd: existing?.cwd || WORKSPACE_DIR,
+    user: existing?.user || user,
+    provider: agent.provider,
+    model: agent.model,
+    credentialId: agent.credentialId || null,
+    fallbackCredentialIds: agent.fallbackCredentialIds || [],
+    apiEndpoint: agent.apiEndpoint || null,
+    gatewayProfileId: agent.gatewayProfileId || null,
+    claudeSessionId: existing?.claudeSessionId || null,
+    codexThreadId: existing?.codexThreadId || null,
+    opencodeSessionId: existing?.opencodeSessionId || null,
+    delegateResumeIds: existing?.delegateResumeIds || buildEmptyDelegateResumeIds(),
+    messages: Array.isArray(existing?.messages) ? existing.messages : [],
+    createdAt: existing?.createdAt || createdAt,
+    lastActiveAt: createdAt,
+    active: existing?.active || false,
+    sessionType: existing?.sessionType || 'human',
+    agentId: agent.id,
+    parentSessionId: existing?.parentSessionId || null,
+    plugins: agent.plugins || agent.tools || [],
+    tools: agent.plugins || agent.tools || [],
+    heartbeatEnabled: agent.heartbeatEnabled || false,
+    heartbeatIntervalSec: agent.heartbeatIntervalSec || null,
+    heartbeatTarget: existing?.heartbeatTarget || null,
+    sessionResetMode: existing?.sessionResetMode || null,
+    sessionIdleTimeoutSec: existing?.sessionIdleTimeoutSec || null,
+    sessionMaxAgeSec: existing?.sessionMaxAgeSec || null,
+    sessionDailyResetAt: existing?.sessionDailyResetAt || null,
+    sessionResetTimezone: existing?.sessionResetTimezone || null,
+    thinkingLevel: existing?.thinkingLevel || null,
+    browserProfileId: existing?.browserProfileId || null,
+    connectorThinkLevel: existing?.connectorThinkLevel || null,
+    connectorSessionScope: existing?.connectorSessionScope || null,
+    connectorReplyMode: existing?.connectorReplyMode || null,
+    connectorThreadBinding: existing?.connectorThreadBinding || null,
+    connectorGroupPolicy: existing?.connectorGroupPolicy || null,
+    connectorIdleTimeoutSec: existing?.connectorIdleTimeoutSec || null,
+    connectorMaxAgeSec: existing?.connectorMaxAgeSec || null,
+    mailbox: existing?.mailbox || null,
+    connectorContext: existing?.connectorContext || undefined,
+    lastAutoMemoryAt: existing?.lastAutoMemoryAt || null,
+    lastHeartbeatText: existing?.lastHeartbeatText || null,
+    lastHeartbeatSentAt: existing?.lastHeartbeatSentAt || null,
+    lastSessionResetAt: existing?.lastSessionResetAt || null,
+    lastSessionResetReason: existing?.lastSessionResetReason || null,
+    identityState: existing?.identityState || null,
+    sessionArchiveState: existing?.sessionArchiveState || null,
+    pinned: existing?.pinned || false,
+    file: existing?.file || null,
+    queuedCount: existing?.queuedCount,
+    currentRunId: existing?.currentRunId || null,
+    conversationTone: existing?.conversationTone,
+    emoji: existing?.emoji,
+    creature: existing?.creature,
+    vibe: existing?.vibe,
+    theme: existing?.theme,
+    avatar: existing?.avatar,
+    canvasContent: existing?.canvasContent || null,
+  }
+  return applyResolvedRoute(baseSession, resolvePrimaryAgentRoute(agent))
+}
+
+export function ensureAgentThreadSession(agentId: string, user = 'default'): Session | null {
+  const agents = loadAgents()
+  const agent = agents[agentId] as Agent | undefined
+  if (!agent) return null
+
+  const sessions = loadSessions()
+  const now = Date.now()
+
+  const existingId = typeof agent.threadSessionId === 'string' ? agent.threadSessionId : ''
+  if (existingId && sessions[existingId]) {
+    const session = buildThreadSession(agent, existingId, user, now, sessions[existingId] as Session)
+    sessions[existingId] = session
+    saveSessions(sessions)
+    return session
+  }
+
+  const legacySession = Object.values(sessions).find((session) => (
+    (session.shortcutForAgentId === agentId || session.name === `agent-thread:${agentId}`)
+    && session.user === user
+  )) as Session | undefined
+
+  if (legacySession) {
+    agent.threadSessionId = legacySession.id
+    agent.updatedAt = now
+    saveAgents(agents)
+    const session = buildThreadSession(agent, legacySession.id, user, now, legacySession)
+    sessions[legacySession.id] = session
+    saveSessions(sessions)
+    return session
+  }
+
+  const sessionId = `agent-chat-${agentId}-${genId()}`
+  const session = buildThreadSession(agent, sessionId, user, now)
+  sessions[sessionId] = session
+  saveSessions(sessions)
+
+  agent.threadSessionId = sessionId
+  agent.updatedAt = now
+  saveAgents(agents)
+  return session
+}

package/src/lib/server/data-dir.test.ts

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { describe, it } from 'node:test'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
+
+function extractLastJson(stdout: string): Record<string, unknown> {
+  const lines = stdout
+    .trim()
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+  const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
+  return JSON.parse(jsonLine || '{}')
+}
+
+describe('data-dir resolution', () => {
+  it('falls back to in-project workspace when the external workspace root exists but child writes fail', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-data-dir-'))
+    const fakeHome = path.join(tempDir, 'home')
+    const dataDir = path.join(tempDir, 'data')
+    const externalWorkspace = path.join(fakeHome, '.swarmclaw', 'workspace')
+    fs.mkdirSync(externalWorkspace, { recursive: true })
+    fs.chmodSync(externalWorkspace, 0o555)
+
+    try {
+      const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', `
+        const modNs = await import('./src/lib/server/data-dir.ts')
+        const mod = modNs.default || modNs['module.exports'] || modNs
+        console.log(JSON.stringify({
+          dataDir: mod.DATA_DIR,
+          workspaceDir: mod.WORKSPACE_DIR,
+        }))
+      `], {
+        cwd: repoRoot,
+        env: {
+          ...process.env,
+          HOME: fakeHome,
+          DATA_DIR: dataDir,
+        },
+        encoding: 'utf-8',
+      })
+
+      assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+      const payload = extractLastJson(result.stdout || '')
+      assert.equal(payload.dataDir, dataDir)
+      assert.equal(payload.workspaceDir, path.join(dataDir, 'workspace'))
+    } finally {
+      fs.chmodSync(externalWorkspace, 0o755)
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/lib/server/data-dir.ts

@@ -4,18 +4,26 @@ import fs from 'fs'
 
 export const DATA_DIR = process.env.DATA_DIR || path.join(process.cwd(), 'data')
 
+function supportsChildWrites(dir: string): boolean {
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    const probeDir = fs.mkdtempSync(path.join(dir, '.swarmclaw-probe-'))
+    fs.rmSync(probeDir, { recursive: true, force: true })
+    return true
+  } catch {
+    return false
+  }
+}
+
 // Workspace lives outside the project directory to avoid triggering Next.js HMR
 // when agents create/modify files. Falls back to data/workspace for Docker/CI.
 function resolveWorkspaceDir(): string {
   if (process.env.WORKSPACE_DIR) return process.env.WORKSPACE_DIR
   const external = path.join(os.homedir(), '.swarmclaw', 'workspace')
-  try {
-    fs.mkdirSync(external, { recursive: true })
+  if (supportsChildWrites(external)) {
     return external
-  } catch {
-    // If we can't create the external dir (permissions, etc.), fall back to in-project
-    return path.join(DATA_DIR, 'workspace')
   }
+  return path.join(DATA_DIR, 'workspace')
 }
 
 export const WORKSPACE_DIR = resolveWorkspaceDir()
@@ -23,12 +31,10 @@ export const WORKSPACE_DIR = resolveWorkspaceDir()
 function resolveBrowserProfilesDir(): string {
   if (process.env.BROWSER_PROFILES_DIR) return process.env.BROWSER_PROFILES_DIR
   const external = path.join(os.homedir(), '.swarmclaw', 'browser-profiles')
-  try {
-    fs.mkdirSync(external, { recursive: true })
+  if (supportsChildWrites(external)) {
     return external
-  } catch {
-    return path.join(DATA_DIR, 'browser-profiles')
   }
+  return path.join(DATA_DIR, 'browser-profiles')
 }
 
 export const BROWSER_PROFILES_DIR = resolveBrowserProfilesDir()

package/src/lib/server/heartbeat-service.ts

@@ -12,6 +12,7 @@ import { log } from './logger'
 import { WORKSPACE_DIR } from './data-dir'
 import { drainSystemEvents } from './system-events'
 import { buildIdentityContinuityContext } from './identity-continuity'
+import { ensureAgentThreadSession } from './agent-thread-session'
 
 const HEARTBEAT_TICK_MS = 5_000
 
@@ -358,8 +359,12 @@ async function tickHeartbeats() {
     return
   }
 
-  const sessions = loadSessions()
   const agents = loadAgents()
+  for (const agent of Object.values(agents) as any[]) {
+    if (!agent?.id || agent.heartbeatEnabled !== true) continue
+    ensureAgentThreadSession(String(agent.id))
+  }
+  const sessions = loadSessions()
   const hasScopedAgents = Object.values(agents).some((a: any) => a?.heartbeatEnabled === true)
 
   // Prune tracked sessions that no longer exist or have heartbeat disabled
@@ -377,7 +382,6 @@ async function tickHeartbeats() {
 
   for (const session of Object.values(sessions) as any[]) {
     if (!session?.id) continue
-    if (!Array.isArray(session.plugins) || session.plugins.length === 0) continue
     if (session.sessionType && session.sessionType !== 'human') continue
 
     // Check if this session or its agent has explicit heartbeat opt-in
@@ -402,8 +406,13 @@ async function tickHeartbeats() {
       : Math.max(cfg.intervalSec * 2, 180)
     const userIdleThresholdSec = resolveHeartbeatUserIdleSec(settings, defaultIdleSec)
     const lastUserAt = lastUserMessageAt(session)
-    if (lastUserAt <= 0) continue
-    const idleMs = now - lastUserAt
+    const baselineAt = lastUserAt > 0
+      ? lastUserAt
+      : explicitOptIn
+        ? (typeof session.lastActiveAt === 'number' ? session.lastActiveAt : (typeof session.createdAt === 'number' ? session.createdAt : 0))
+        : 0
+    if (baselineAt <= 0) continue
+    const idleMs = now - baselineAt
     if (idleMs < userIdleThresholdSec * 1000) continue
 
     const last = state.lastBySession.get(session.id) || 0

package/src/lib/server/heartbeat-wake.ts

@@ -3,6 +3,7 @@
  * Requests are debounced with a 250ms coalesce window to batch rapid-fire events.
  */
 
+import { ensureAgentThreadSession } from './agent-thread-session'
 import { loadSessions, loadAgents, loadSettings } from './storage'
 import { enqueueSessionRun } from './session-run-manager'
 import { log } from './logger'
@@ -29,7 +30,6 @@ function flushWakes(): void {
   const wakes = new Map(state.pending)
   state.pending.clear()
 
-  const sessions = loadSessions()
   const agents = loadAgents()
   const settings = loadSettings()
 
@@ -39,6 +39,7 @@ function flushWakes(): void {
 
       // If only agentId provided, find the agent's most recently active session
       if (!sessionId && wake.agentId) {
+        const sessions = loadSessions()
         let bestSession: { id: string; lastActiveAt: number } | null = null
         for (const s of Object.values(sessions) as Array<Record<string, unknown>>) {
           if (s.agentId !== wake.agentId) continue
@@ -48,11 +49,14 @@ function flushWakes(): void {
           }
         }
         sessionId = bestSession?.id
+        if (!sessionId) {
+          sessionId = ensureAgentThreadSession(wake.agentId)?.id
+        }
       }
 
       if (!sessionId) continue
 
-      const session = sessions[sessionId] as Record<string, unknown> | undefined
+      const session = loadSessions()[sessionId] as Record<string, unknown> | undefined
       if (!session) continue
 
       const agentId = (session.agentId || wake.agentId) as string | undefined