@swarmclawai/swarmclaw 1.9.21 → 1.9.23

package/src/lib/server/schedules/schedule-lifecycle.ts

@@ -1,5 +1,3 @@
-import { CronExpressionParser } from 'cron-parser'
-
 import { genId } from '@/lib/id'
 import type { BoardTask, Schedule, ScheduleStatus, Session } from '@/types'
 import { pushMainLoopEventToMainSessions } from '@/lib/server/agents/main-agent-loop'
@@ -19,6 +17,7 @@ import {
 import { notify } from '@/lib/server/ws-hub'
 import { getScheduleClusterIds } from '@/lib/server/schedules/schedule-service'
 import { appendScheduleHistoryEntry } from '@/lib/server/schedules/schedule-history'
+import { computeScheduleNextRunAt } from '@/lib/server/schedules/schedule-timing'
 
 type RestorableScheduleStatus = Exclude<ScheduleStatus, 'archived'>
 
@@ -50,33 +49,11 @@ export interface SchedulePurgeResult {
 }
 
 function computeNextRunAt(schedule: Pick<Schedule, 'scheduleType' | 'cron' | 'intervalMs' | 'runAt' | 'timezone' | 'staggerSec'>, now: number): number | undefined {
-  const applyStagger = (timestamp: number): number => {
-    if (!schedule.staggerSec || schedule.staggerSec <= 0) return timestamp
-    return timestamp + Math.floor(Math.random() * schedule.staggerSec * 1000)
-  }
-
-  if (schedule.scheduleType === 'once') {
-    return typeof schedule.runAt === 'number' && Number.isFinite(schedule.runAt)
-      ? applyStagger(schedule.runAt)
-      : undefined
-  }
-  if (schedule.scheduleType === 'interval') {
-    return typeof schedule.intervalMs === 'number' && Number.isFinite(schedule.intervalMs)
-      ? applyStagger(now + schedule.intervalMs)
-      : undefined
-  }
-  if (schedule.scheduleType === 'cron' && typeof schedule.cron === 'string' && schedule.cron.trim()) {
-    try {
-      const interval = CronExpressionParser.parse(
-        schedule.cron,
-        schedule.timezone ? { tz: schedule.timezone } : undefined,
-      )
-      return applyStagger(interval.next().getTime())
-    } catch {
-      return undefined
-    }
+  try {
+    return computeScheduleNextRunAt(schedule, now)
+  } catch {
+    return undefined
   }
-  return undefined
 }
 
 function cloneSchedule(schedule: Schedule): Schedule {

package/src/lib/server/schedules/schedule-normalization.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { CronExpressionParser } from 'cron-parser'
 import { WORKSPACE_DIR } from '@/lib/server/data-dir'
+import { computeScheduleNextRunAt } from '@/lib/server/schedules/schedule-timing'
 
 type SchedulePayload = Record<string, unknown>
 
@@ -86,15 +86,6 @@ function parseAtTimeToCron(atTime: string): string | null {
   return `${minutes} ${hours} * * *`
 }
 
-/**
- * Apply a random stagger offset (in seconds) to a timestamp.
- */
-function applyStagger(timestamp: number, staggerSec: number | null | undefined): number {
-  if (!staggerSec || staggerSec <= 0) return timestamp
-  const offset = Math.floor(Math.random() * staggerSec * 1000)
-  return timestamp + offset
-}
-
 function normalizePositiveInt(value: unknown): number | null {
   const parsed = typeof value === 'number'
     ? value
@@ -326,24 +317,11 @@ export function normalizeSchedulePayload(payload: SchedulePayload, opts: Normali
   }
 
   if (normalized.status !== 'archived' && normalized.nextRunAt == null) {
-    if (normalized.scheduleType === 'once') {
-      if (runAt != null) normalized.nextRunAt = applyStagger(runAt, normalized.staggerSec as number | null)
-    } else if (normalized.scheduleType === 'interval') {
-      if (intervalMs != null) normalized.nextRunAt = applyStagger(now + intervalMs, normalized.staggerSec as number | null)
-    } else if (normalized.scheduleType === 'cron' && normalized.cron) {
-      try {
-        const cronTimezone = trimString(normalized.timezone)
-        const interval = CronExpressionParser.parse(
-          normalized.cron as string,
-          {
-            ...(cronTimezone ? { tz: cronTimezone } : {}),
-            currentDate: new Date(now),
-          },
-        )
-        normalized.nextRunAt = applyStagger(interval.next().getTime(), normalized.staggerSec as number | null)
-      } catch {
-        return { ok: false, error: 'Error: invalid cron expression.' }
-      }
+    try {
+      const computedNextRunAt = computeScheduleNextRunAt(normalized, now)
+      if (computedNextRunAt != null) normalized.nextRunAt = computedNextRunAt
+    } catch {
+      return { ok: false, error: 'Error: invalid cron expression.' }
     }
   }
 

package/src/lib/server/schedules/schedule-timing.test.ts

@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import {
+  assessScheduleNextRunRepair,
+  computeScheduleNextRunAt,
+  stableScheduleStaggerMs,
+} from '@/lib/server/schedules/schedule-timing'
+
+describe('schedule timing', () => {
+  it('computes cron next runs from the provided scheduler time', () => {
+    const nextRunAt = computeScheduleNextRunAt({
+      id: 'sched-daily',
+      name: 'Daily status',
+      agentId: 'agent-1',
+      scheduleType: 'cron',
+      cron: '0 8 * * *',
+      timezone: 'UTC',
+    }, Date.parse('2030-01-01T08:00:30.000Z'))
+
+    assert.equal(nextRunAt, Date.parse('2030-01-02T08:00:00.000Z'))
+  })
+
+  it('uses deterministic schedule stagger inside the configured window', () => {
+    const schedule = {
+      id: 'sched-staggered',
+      name: 'Staggered status',
+      agentId: 'agent-1',
+      scheduleType: 'cron',
+      cron: '0 8 * * *',
+      timezone: 'UTC',
+      staggerSec: 30,
+    }
+
+    const first = stableScheduleStaggerMs(schedule)
+    const second = stableScheduleStaggerMs(schedule)
+
+    assert.equal(first, second)
+    assert.ok(first >= 0)
+    assert.ok(first < 30_000)
+  })
+
+  it('repairs stale future cron slots to the earliest upcoming slot', () => {
+    const assessment = assessScheduleNextRunRepair({
+      id: 'sched-stale',
+      name: 'Daily status',
+      agentId: 'agent-1',
+      scheduleType: 'cron',
+      cron: '0 8 * * *',
+      timezone: 'UTC',
+      status: 'active',
+      nextRunAt: Date.parse('2026-05-12T08:00:00.000Z'),
+    }, Date.parse('2026-05-06T07:30:00.000Z'))
+
+    assert.equal(assessment.ok, true)
+    assert.equal(assessment.repair, true)
+    if (assessment.ok && assessment.repair) {
+      assert.equal(assessment.reason, 'stale_future')
+      assert.equal(assessment.nextRunAt, Date.parse('2026-05-06T08:00:00.000Z'))
+    }
+  })
+
+  it('flags invalid due cron schedules before they launch', () => {
+    const assessment = assessScheduleNextRunRepair({
+      id: 'sched-invalid',
+      name: 'Broken cron',
+      agentId: 'agent-1',
+      scheduleType: 'cron',
+      cron: 'not a cron',
+      status: 'active',
+      nextRunAt: Date.parse('2026-05-06T07:00:00.000Z'),
+    }, Date.parse('2026-05-06T07:30:00.000Z'))
+
+    assert.equal(assessment.ok, false)
+    if (!assessment.ok) {
+      assert.equal(assessment.reason, 'invalid_cron')
+      assert.equal(assessment.previousNextRunAt, Date.parse('2026-05-06T07:00:00.000Z'))
+    }
+  })
+})

package/src/lib/server/schedules/schedule-timing.ts

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto'
+
+import { CronExpressionParser } from 'cron-parser'
+
+import type { ScheduleType } from '@/types'
+
+export type ScheduleTimingRepairReason = 'missing' | 'invalid' | 'stale_future'
+
+export type ScheduleTimingInput = {
+  id?: string | null
+  name?: string | null
+  agentId?: string | null
+  taskPrompt?: string | null
+  scheduleType?: ScheduleType | string | null
+  cron?: string | null
+  intervalMs?: number | null
+  runAt?: number | null
+  timezone?: string | null
+  staggerSec?: number | null
+  nextRunAt?: number | null
+  status?: string | null
+}
+
+export type ScheduleNextRunRepairAssessment =
+  | { ok: true; repair: false }
+  | {
+      ok: true
+      repair: true
+      reason: ScheduleTimingRepairReason
+      nextRunAt: number
+      previousNextRunAt: number | null
+    }
+  | {
+      ok: false
+      reason: 'invalid_cron'
+      previousNextRunAt: number | null
+    }
+
+const CRON_REPAIR_TOLERANCE_MS = 1_000
+
+function trimString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function normalizeTimestamp(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null
+  const normalized = Math.trunc(value)
+  return normalized > 0 ? normalized : null
+}
+
+function normalizeNow(value: number): number {
+  return Number.isFinite(value) ? Math.trunc(value) : Date.now()
+}
+
+function normalizeStaggerWindowMs(staggerSec: unknown): number {
+  if (typeof staggerSec !== 'number' || !Number.isFinite(staggerSec) || staggerSec <= 0) return 0
+  return Math.min(Math.trunc(staggerSec * 1000), Number.MAX_SAFE_INTEGER)
+}
+
+function stableScheduleKey(schedule: ScheduleTimingInput): string {
+  return [
+    trimString(schedule.id),
+    trimString(schedule.agentId),
+    trimString(schedule.name),
+    trimString(schedule.taskPrompt),
+    trimString(schedule.scheduleType),
+    trimString(schedule.cron),
+    typeof schedule.intervalMs === 'number' && Number.isFinite(schedule.intervalMs) ? Math.trunc(schedule.intervalMs) : '',
+    typeof schedule.runAt === 'number' && Number.isFinite(schedule.runAt) ? Math.trunc(schedule.runAt) : '',
+    trimString(schedule.timezone),
+  ].join('\0')
+}
+
+export function stableScheduleStaggerMs(schedule: ScheduleTimingInput): number {
+  const windowMs = normalizeStaggerWindowMs(schedule.staggerSec)
+  if (windowMs <= 0) return 0
+  const digest = createHash('sha256').update(stableScheduleKey(schedule)).digest()
+  const value = digest.readBigUInt64BE(0)
+  return Number(value % BigInt(windowMs))
+}
+
+function applyStableStagger(timestamp: number, schedule: ScheduleTimingInput): number {
+  return Math.trunc(timestamp + stableScheduleStaggerMs(schedule))
+}
+
+function parseCron(schedule: ScheduleTimingInput, now: number) {
+  const cron = trimString(schedule.cron)
+  if (!cron) return null
+  const timezone = trimString(schedule.timezone)
+  return CronExpressionParser.parse(cron, {
+    ...(timezone ? { tz: timezone } : {}),
+    currentDate: new Date(normalizeNow(now)),
+  })
+}
+
+export function computeScheduleNextRunAt(schedule: ScheduleTimingInput, now: number): number | undefined {
+  const scheduleType = trimString(schedule.scheduleType)
+  if (scheduleType === 'once') {
+    const runAt = normalizeTimestamp(schedule.runAt)
+    return runAt == null ? undefined : applyStableStagger(runAt, schedule)
+  }
+  if (scheduleType === 'interval') {
+    const intervalMs = normalizeTimestamp(schedule.intervalMs)
+    return intervalMs == null ? undefined : applyStableStagger(normalizeNow(now) + intervalMs, schedule)
+  }
+  if (scheduleType === 'cron') {
+    const interval = parseCron(schedule, now)
+    if (!interval) return undefined
+    return applyStableStagger(interval.next().getTime(), schedule)
+  }
+  return undefined
+}
+
+function computeCronWindow(schedule: ScheduleTimingInput, now: number): { earliest: number; latest: number; nextRunAt: number } | null {
+  const interval = parseCron(schedule, now)
+  if (!interval) return null
+  const earliest = interval.next().getTime()
+  const latest = earliest + normalizeStaggerWindowMs(schedule.staggerSec)
+  return {
+    earliest,
+    latest,
+    nextRunAt: applyStableStagger(earliest, schedule),
+  }
+}
+
+export function assessScheduleNextRunRepair(
+  schedule: ScheduleTimingInput,
+  now: number,
+): ScheduleNextRunRepairAssessment {
+  if (trimString(schedule.status) && trimString(schedule.status) !== 'active') return { ok: true, repair: false }
+
+  const previousNextRunAt = normalizeTimestamp(schedule.nextRunAt)
+  const hasNextRunAt = schedule.nextRunAt != null
+  if (previousNextRunAt != null && previousNextRunAt <= normalizeNow(now)) {
+    if (trimString(schedule.scheduleType) === 'cron') {
+      try {
+        if (!parseCron(schedule, now)) return { ok: false, reason: 'invalid_cron', previousNextRunAt }
+      } catch {
+        return { ok: false, reason: 'invalid_cron', previousNextRunAt }
+      }
+    }
+    return { ok: true, repair: false }
+  }
+
+  if (previousNextRunAt == null) {
+    try {
+      const nextRunAt = computeScheduleNextRunAt(schedule, now)
+      if (nextRunAt == null) return { ok: true, repair: false }
+      return {
+        ok: true,
+        repair: true,
+        reason: hasNextRunAt ? 'invalid' : 'missing',
+        nextRunAt,
+        previousNextRunAt: null,
+      }
+    } catch {
+      return { ok: false, reason: 'invalid_cron', previousNextRunAt: null }
+    }
+  }
+
+  if (trimString(schedule.scheduleType) !== 'cron') return { ok: true, repair: false }
+
+  try {
+    const window = computeCronWindow(schedule, now)
+    if (!window) return { ok: true, repair: false }
+    const tooEarly = previousNextRunAt < window.earliest - CRON_REPAIR_TOLERANCE_MS
+    const tooLate = previousNextRunAt > window.latest + CRON_REPAIR_TOLERANCE_MS
+    if (!tooEarly && !tooLate) return { ok: true, repair: false }
+    return {
+      ok: true,
+      repair: true,
+      reason: 'stale_future',
+      nextRunAt: window.nextRunAt,
+      previousNextRunAt,
+    }
+  } catch {
+    return { ok: false, reason: 'invalid_cron', previousNextRunAt }
+  }
+}

package/src/lib/server/session-tools/web-crawl.test.ts

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict'
+import { afterEach, describe, it } from 'node:test'
+import { buildWebTools } from './web'
+import type { ToolBuildContext } from './context'
+
+const originalFetch = globalThis.fetch
+
+function createContext(): ToolBuildContext {
+  return {
+    cwd: process.cwd(),
+    ctx: undefined,
+    hasExtension: (name: string) => name === 'web',
+    hasTool: (name: string) => name === 'web',
+    cleanupFns: [],
+    commandTimeoutMs: 1000,
+    claudeTimeoutMs: 1000,
+    cliProcessTimeoutMs: 1000,
+    persistDelegateResumeId: () => {},
+    readStoredDelegateResumeId: () => null,
+    resolveCurrentSession: () => null,
+    activeExtensions: ['web'],
+  } as ToolBuildContext
+}
+
+function mockFetch(pages: Record<string, string>, calls: string[] = []): void {
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    const url = input instanceof Request ? input.url : String(input)
+    calls.push(url)
+    const html = pages[url]
+    if (!html) {
+      return new Response('missing', { status: 404, statusText: 'Not Found' })
+    }
+    return new Response(html, {
+      status: 200,
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    })
+  }) as typeof fetch
+}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+describe('web extract and crawl tools', () => {
+  it('registers direct granular web tools when web is enabled', () => {
+    const names = buildWebTools(createContext()).map((entry) => entry.name).sort()
+
+    assert.deepEqual(names.filter((name) => name.startsWith('web')), [
+      'web',
+      'web_crawl',
+      'web_extract',
+      'web_fetch',
+      'web_search',
+    ])
+  })
+
+  it('extracts readable page content with title and source URL', async () => {
+    mockFetch({
+      'https://example.test/article': `
+        <!doctype html>
+        <title>Feature Page</title>
+        <header>Ignore navigation</header>
+        <main>
+          <h1>Feature Page</h1>
+          <p>Readable body text for the agent.</p>
+        </main>
+        <script>console.log('hidden')</script>
+      `,
+    })
+    const tool = buildWebTools(createContext()).find((entry) => entry.name === 'web_extract')
+    assert.ok(tool)
+
+    const output = String(await tool.invoke({ url: 'https://example.test/article#section' }))
+
+    assert.match(output, /Title: Feature Page/)
+    assert.match(output, /URL: https:\/\/example\.test\/article/)
+    assert.match(output, /Readable body text for the agent\./)
+    assert.doesNotMatch(output, /Ignore navigation/)
+    assert.doesNotMatch(output, /console\.log/)
+  })
+
+  it('crawls same-origin pages within the requested page and depth bounds', async () => {
+    const calls: string[] = []
+    mockFetch({
+      'https://site.test/': `
+        <title>Start</title>
+        <main>Start page <a href="/a">A</a> <a href="/b">B</a> <a href="https://external.test/x">External</a></main>
+      `,
+      'https://site.test/a': '<title>A page</title><main>Alpha content</main>',
+      'https://site.test/b': '<title>B page</title><main>Beta content</main>',
+      'https://external.test/x': '<title>External</title><main>Should not be fetched</main>',
+    }, calls)
+    const tool = buildWebTools(createContext()).find((entry) => entry.name === 'web_crawl')
+    assert.ok(tool)
+
+    const output = String(await tool.invoke({ url: 'https://site.test/', maxPages: 3, maxDepth: 1 }))
+
+    assert.match(output, /Crawl results for: https:\/\/site\.test\//)
+    assert.match(output, /Pages crawled: 3/)
+    assert.match(output, /Start page/)
+    assert.match(output, /Alpha content/)
+    assert.match(output, /Beta content/)
+    assert.doesNotMatch(output, /Should not be fetched/)
+    assert.deepEqual(calls, ['https://site.test/', 'https://site.test/a', 'https://site.test/b'])
+  })
+})

package/src/lib/server/session-tools/web-inputs.test.ts

@@ -20,6 +20,11 @@ describe('inferWebActionFromArgs', () => {
     assert.equal(inferWebActionFromArgs({ action: 'search', url: 'https://example.com/article' }), 'search')
   })
 
+  it('preserves explicit extract and crawl actions', () => {
+    assert.equal(inferWebActionFromArgs({ action: 'extract', url: 'https://example.com/article' }), 'extract')
+    assert.equal(inferWebActionFromArgs({ action: 'crawl', url: 'https://example.com/' }), 'crawl')
+  })
+
   it('normalizes stringified browser form payloads', () => {
     const normalized = normalizeBrowserActionParams({
       input: JSON.stringify({

package/src/lib/server/session-tools/web-utils.ts

@@ -176,8 +176,14 @@ export function inferWebActionFromArgs(params: {
   query?: string
   url?: string
   method?: string
-}): 'search' | 'fetch' | 'api' | undefined {
-  if (params.action === 'search' || params.action === 'fetch' || params.action === 'api') return params.action
+}): 'search' | 'fetch' | 'extract' | 'crawl' | 'api' | undefined {
+  if (
+    params.action === 'search'
+    || params.action === 'fetch'
+    || params.action === 'extract'
+    || params.action === 'crawl'
+    || params.action === 'api'
+  ) return params.action
   if (typeof params.method === 'string' && params.method.trim()) return 'api'
   if (typeof params.url === 'string' && /^https?:\/\//i.test(params.url.trim())) return 'fetch'
   if (typeof params.query === 'string' && params.query.trim()) return 'search'