@swarmclawai/swarmclaw 0.7.2 → 0.7.3

package/src/lib/server/session-tools/mailbox.ts

@@ -0,0 +1,276 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import type { Plugin, PluginHooks } from '@/types'
+import { getPluginManager } from '../plugins'
+import type { ToolBuildContext } from './context'
+import { normalizeToolInputArgs } from './normalize-tool-args'
+import {
+  downloadMailboxAttachment,
+  fetchMailboxMessageByUid,
+  fetchMailboxMessages,
+  getMailboxConfig,
+  replyMailboxMessage,
+} from '../mailbox-utils'
+import { createWatchJob } from '../watch-jobs'
+
+function parseMessageUid(value: unknown): number {
+  const parsed = typeof value === 'number' ? value : typeof value === 'string' ? Number.parseInt(value, 10) : Number.NaN
+  return Number.isFinite(parsed) ? Math.max(0, Math.trunc(parsed)) : 0
+}
+
+async function executeMailboxAction(args: Record<string, unknown>, bctx: { cwd: string; sessionId?: string | null; agentId?: string | null }) {
+  const normalized = normalizeToolInputArgs(args)
+  const action = String(normalized.action || 'status').trim().toLowerCase()
+  const folder = typeof normalized.folder === 'string' ? normalized.folder.trim() : undefined
+
+  try {
+    if (action === 'status') {
+      const config = getMailboxConfig()
+      return JSON.stringify({
+        configured: !!(config.imapHost && config.user && config.password),
+        imapHost: config.imapHost || null,
+        smtpHost: config.smtpHost || null,
+        folder: config.folder || 'INBOX',
+        fromAddress: config.fromAddress || null,
+        subjectPrefix: config.subjectPrefix || null,
+      })
+    }
+
+    if (action === 'list_messages' || action === 'search_messages') {
+      const messages = await fetchMailboxMessages({
+        folder,
+        query: typeof normalized.query === 'string' ? normalized.query : undefined,
+        from: typeof normalized.from === 'string' ? normalized.from : undefined,
+        subjectContains: typeof normalized.subjectContains === 'string' ? normalized.subjectContains : undefined,
+        bodyContains: typeof normalized.containsText === 'string' ? normalized.containsText : undefined,
+        unreadOnly: normalized.unreadOnly === true,
+        hasAttachments: normalized.hasAttachments === true,
+        limit: typeof normalized.limit === 'number' ? normalized.limit : undefined,
+      })
+      return JSON.stringify(messages.map((message) => ({
+        uid: message.uid,
+        messageId: message.messageId,
+        subject: message.subject,
+        from: message.from,
+        fromName: message.fromName,
+        date: message.date,
+        snippet: message.snippet,
+        hasAttachments: message.hasAttachments,
+        attachmentCount: message.attachments.length,
+        threadKey: message.threadKey,
+      })))
+    }
+
+    if (action === 'list_threads') {
+      const messages = await fetchMailboxMessages({
+        folder,
+        limit: typeof normalized.limit === 'number' ? Math.max(10, normalized.limit * 4) : 80,
+      })
+      const threads = new Map<string, {
+        threadKey: string
+        subject: string
+        participants: Set<string>
+        latestUid: number
+        latestDate: string | null
+        messageCount: number
+        unreadCount: number
+        snippet: string
+      }>()
+      for (const message of messages) {
+        const current = threads.get(message.threadKey) || {
+          threadKey: message.threadKey,
+          subject: message.subject,
+          participants: new Set<string>(),
+          latestUid: message.uid,
+          latestDate: message.date,
+          messageCount: 0,
+          unreadCount: 0,
+          snippet: message.snippet,
+        }
+        current.messageCount += 1
+        current.participants.add(message.from)
+        if (!message.flags.includes('\\Seen')) current.unreadCount += 1
+        if (message.uid >= current.latestUid) {
+          current.latestUid = message.uid
+          current.latestDate = message.date
+          current.subject = message.subject
+          current.snippet = message.snippet
+        }
+        threads.set(message.threadKey, current)
+      }
+      return JSON.stringify(Array.from(threads.values())
+        .map((thread) => ({
+          threadKey: thread.threadKey,
+          subject: thread.subject,
+          participants: Array.from(thread.participants),
+          latestUid: thread.latestUid,
+          latestDate: thread.latestDate,
+          messageCount: thread.messageCount,
+          unreadCount: thread.unreadCount,
+          snippet: thread.snippet,
+        }))
+        .sort((a, b) => b.latestUid - a.latestUid)
+        .slice(0, Math.max(1, Math.min(typeof normalized.limit === 'number' ? normalized.limit : 20, 100))))
+    }
+
+    if (action === 'read_message') {
+      const uid = parseMessageUid(normalized.uid ?? normalized.id)
+      if (!uid) return 'Error: uid is required.'
+      const message = await fetchMailboxMessageByUid(uid, folder)
+      if (!message) return `Error: mailbox message "${uid}" not found.`
+      return JSON.stringify(message)
+    }
+
+    if (action === 'download_attachment') {
+      const uid = parseMessageUid(normalized.uid ?? normalized.id)
+      if (!uid) return 'Error: uid is required.'
+      const result = await downloadMailboxAttachment({
+        uid,
+        folder,
+        attachmentId: typeof normalized.attachmentId === 'string' ? normalized.attachmentId : undefined,
+        attachmentName: typeof normalized.attachmentName === 'string' ? normalized.attachmentName : undefined,
+        saveTo: typeof normalized.saveTo === 'string' ? normalized.saveTo : undefined,
+        cwd: bctx.cwd,
+      })
+      return JSON.stringify(result)
+    }
+
+    if (action === 'reply') {
+      const uid = parseMessageUid(normalized.uid ?? normalized.id)
+      if (!uid) return 'Error: uid is required.'
+      const text = typeof normalized.text === 'string'
+        ? normalized.text
+        : typeof normalized.body === 'string'
+          ? normalized.body
+          : ''
+      if (!text.trim()) return 'Error: text is required.'
+      const result = await replyMailboxMessage({
+        uid,
+        folder,
+        text,
+        html: typeof normalized.html === 'string' ? normalized.html : undefined,
+        subject: typeof normalized.subject === 'string' ? normalized.subject : undefined,
+      })
+      return JSON.stringify({ ok: true, ...result, uid })
+    }
+
+    if (action === 'wait_for_email') {
+      if (!bctx.sessionId && !bctx.agentId) return 'Error: email waits require a session or agent context.'
+      const resumeMessage = typeof normalized.resumeMessage === 'string' && normalized.resumeMessage.trim()
+        ? normalized.resumeMessage.trim()
+        : 'A matching email arrived. Read it, decide what to do next, and continue the task.'
+      const intervalMs = typeof normalized.intervalSec === 'number'
+        ? Math.max(30, normalized.intervalSec) * 1000
+        : 60_000
+      const timeoutAt = typeof normalized.timeoutMinutes === 'number'
+        ? Date.now() + Math.max(1, normalized.timeoutMinutes) * 60_000
+        : undefined
+      const job = await createWatchJob({
+        type: 'email',
+        sessionId: bctx.sessionId || null,
+        agentId: bctx.agentId || null,
+        createdByAgentId: bctx.agentId || null,
+        resumeMessage,
+        description: typeof normalized.description === 'string' ? normalized.description : 'Wait for email',
+        intervalMs,
+        timeoutAt,
+        target: {
+          folder: folder || getMailboxConfig().folder || 'INBOX',
+        },
+        condition: {
+          from: typeof normalized.from === 'string' ? normalized.from : undefined,
+          subjectContains: typeof normalized.subjectContains === 'string' ? normalized.subjectContains : undefined,
+          containsText: typeof normalized.containsText === 'string' ? normalized.containsText : undefined,
+          query: typeof normalized.query === 'string' ? normalized.query : undefined,
+          unreadOnly: normalized.unreadOnly === true,
+          hasAttachments: normalized.hasAttachments === true,
+        },
+      })
+      return JSON.stringify(job)
+    }
+
+    return `Error: Unknown action "${action}".`
+  } catch (err: unknown) {
+    return `Error: ${err instanceof Error ? err.message : String(err)}`
+  }
+}
+
+const MailboxPlugin: Plugin = {
+  name: 'Mailbox',
+  enabledByDefault: false,
+  description: 'Read/search/reply to inbox messages over IMAP/SMTP, download attachments, and wait for matching inbound email.',
+  hooks: {
+    getCapabilityDescription: () =>
+      'I can inspect inboxes with `mailbox`, read and search messages, download attachments, reply to emails, and wait for specific inbound messages.',
+  } as PluginHooks,
+  tools: [
+    {
+      name: 'mailbox',
+      description: 'Work with email inboxes. Actions: status, list_messages, list_threads, search_messages, read_message, download_attachment, reply, wait_for_email.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['status', 'list_messages', 'list_threads', 'search_messages', 'read_message', 'download_attachment', 'reply', 'wait_for_email'] },
+          uid: { type: 'number' },
+          query: { type: 'string' },
+          from: { type: 'string' },
+          subjectContains: { type: 'string' },
+          containsText: { type: 'string' },
+          attachmentId: { type: 'string' },
+          attachmentName: { type: 'string' },
+          text: { type: 'string' },
+          body: { type: 'string' },
+          html: { type: 'string' },
+          subject: { type: 'string' },
+          folder: { type: 'string' },
+          unreadOnly: { type: 'boolean' },
+          hasAttachments: { type: 'boolean' },
+          limit: { type: 'number' },
+          saveTo: { type: 'string' },
+          resumeMessage: { type: 'string' },
+          intervalSec: { type: 'number' },
+          timeoutMinutes: { type: 'number' },
+        },
+        required: ['action'],
+      },
+      execute: async (args, context) => executeMailboxAction(args, {
+        cwd: context.session.cwd || process.cwd(),
+        sessionId: context.session.id,
+        agentId: context.session.agentId || null,
+      }),
+    },
+  ],
+  ui: {
+    settingsFields: [
+      { key: 'imapHost', label: 'IMAP Host', type: 'text', placeholder: 'imap.gmail.com', help: 'Inbound mailbox host.' },
+      { key: 'imapPort', label: 'IMAP Port', type: 'number', defaultValue: 993, help: '993 for TLS IMAP.' },
+      { key: 'smtpHost', label: 'SMTP Host', type: 'text', placeholder: 'smtp.gmail.com', help: 'Outbound mail host for replies.' },
+      { key: 'smtpPort', label: 'SMTP Port', type: 'number', defaultValue: 587, help: '587 for STARTTLS, 465 for SSL.' },
+      { key: 'user', label: 'Mailbox Username', type: 'text', placeholder: 'agent@example.com' },
+      { key: 'password', label: 'Mailbox Password', type: 'secret', help: 'IMAP password or app password.' },
+      { key: 'folder', label: 'Folder', type: 'text', defaultValue: 'INBOX', placeholder: 'INBOX' },
+      { key: 'fromAddress', label: 'Reply From Address', type: 'text', placeholder: 'agent@example.com' },
+      { key: 'fromName', label: 'Reply From Name', type: 'text', defaultValue: 'SwarmClaw Agent' },
+    ],
+  },
+}
+
+getPluginManager().registerBuiltin('mailbox', MailboxPlugin)
+
+export function buildMailboxTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  if (!bctx.hasPlugin('mailbox')) return []
+  return [
+    tool(
+      async (args) => executeMailboxAction(args, {
+        cwd: bctx.cwd,
+        sessionId: bctx.ctx?.sessionId || null,
+        agentId: bctx.ctx?.agentId || null,
+      }),
+      {
+        name: 'mailbox',
+        description: MailboxPlugin.tools![0].description,
+        schema: z.object({}).passthrough(),
+      },
+    ),
+  ]
+}

package/src/lib/server/session-tools/memory.ts

@@ -15,6 +15,8 @@ import type { MemoryEntry, Plugin, PluginHooks } from '@/types'
 import type { ToolBuildContext } from './context'
 import { getPluginManager } from '../plugins'
 import { normalizeToolInputArgs } from './normalize-tool-args'
+import { partitionMemoriesByTier } from '../memory-tiers'
+import { syncSessionArchiveMemory } from '../session-archive-memory'
 
 /**
  * Advanced Database-Backed Memory logic.
@@ -34,6 +36,12 @@ async function executeMemoryAction(input: any, ctx: any) {
   
   const memDb = getMemoryDb()
   const currentAgentId = ctx?.agentId || null
+  const currentSessionId = typeof ctx?.sessionId === 'string'
+    ? ctx.sessionId
+    : typeof ctx?.id === 'string'
+      ? ctx.id
+      : null
+  const currentSession = ctx && typeof ctx === 'object' && Array.isArray(ctx.messages) ? ctx : null
   const rawScope = typeof scope === 'string' ? scope : 'auto'
   const scopeMode = normalizeMemoryScopeMode(rawScope === 'shared' ? 'global' : rawScope)
   const rerankMode = rerank === 'semantic' || rerank === 'lexical' ? rerank : 'balanced'
@@ -41,7 +49,7 @@ async function executeMemoryAction(input: any, ctx: any) {
   const scopeFilter = {
     mode: scopeMode,
     agentId: currentAgentId,
-    sessionId: (typeof scopeSessionId === 'string' && scopeSessionId.trim()) ? scopeSessionId.trim() : (ctx?.sessionId || null),
+    sessionId: (typeof scopeSessionId === 'string' && scopeSessionId.trim()) ? scopeSessionId.trim() : currentSessionId,
     projectRoot: (typeof projectRoot === 'string' && projectRoot.trim()) ? projectRoot.trim() : ((project && typeof project === 'object' && 'rootPath' in project && typeof (project as Record<string, unknown>).rootPath === 'string') ? (project as Record<string, unknown>).rootPath as string : null),
   }
   
@@ -52,6 +60,10 @@ async function executeMemoryAction(input: any, ctx: any) {
   const limits = getMemoryLookupLimits(loadSettings())
   const maxPerLookup = limits.maxPerLookup
 
+  if ((action === 'search' || action === 'list') && currentSession) {
+    try { syncSessionArchiveMemory(currentSession) } catch { /* archive sync is best-effort */ }
+  }
+
   const formatEntry = (m: any) => {
     let line = `[${m.id}] (${m.agentId ? `agent:${m.agentId}` : 'shared'}) ${m.category}/${m.title}: ${m.content}`
     if (m.reinforcementCount) line += ` (reinforced ×${m.reinforcementCount})`
@@ -132,6 +144,8 @@ const MemoryPlugin: Plugin = {
       const agentId = ctx.session.agentId
       if (!agentId) return null
 
+      try { syncSessionArchiveMemory(ctx.session) } catch { /* archive sync is best-effort */ }
+
       const memDb = getMemoryDb()
       const memoryQuerySeed = [
         ctx.message,
@@ -159,12 +173,22 @@ const MemoryPlugin: Plugin = {
       const relevantLookup = memDb.searchWithLinked(memoryQuerySeed, agentId, 1, 10, 14)
       const relevant = relevantLookup.entries.slice(0, relevantSlice)
       const recent = memDb.list(agentId, 12).slice(0, 6)
+      const relevantByTier = partitionMemoriesByTier(relevant)
+      const recentByTier = partitionMemoriesByTier(recent)
+
+      const relevantLines = relevantByTier.durable
+        .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
+        .map(formatMemoryLine)
 
-      const relevantLines = relevant
+      const archiveLines = relevantByTier.archive
         .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
         .map(formatMemoryLine)
 
-      const recentLines = recent
+      const recentLines = recentByTier.durable
+        .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
+        .map(formatMemoryLine)
+
+      const recentArchiveLines = recentByTier.archive
         .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
         .map(formatMemoryLine)
 
@@ -175,14 +199,21 @@ const MemoryPlugin: Plugin = {
       if (relevantLines.length) {
         parts.push(['## Relevant Memory Hits', 'These memories were retrieved by relevance for the current objective.', ...relevantLines].join('\n'))
       }
+      if (archiveLines.length) {
+        parts.push(['## Session Archive Hits', 'Past conversation snapshots that may restore context from older chats.', ...archiveLines].join('\n'))
+      }
       if (recentLines.length) {
         parts.push(['## Recent Memory Notes', 'Recent durable notes that may still apply.', ...recentLines].join('\n'))
       }
+      if (recentArchiveLines.length) {
+        parts.push(['## Recent Session Archives', 'Recently synced conversation archives you can search instead of relying on stale live context.', ...recentArchiveLines].join('\n'))
+      }
 
       // Memory Policy
       parts.push([
         '## My Memory',
         'I have long-term memory that persists across conversations. I use it naturally — I don\'t wait to be asked to remember things.',
+        'Memory tiers: working memory is short-lived, durable memory stores stable facts and decisions, and session archives capture older conversation context for search.',
         '',
         '**Things worth remembering:**',
         '- What the user likes, dislikes, or has corrected me on',
@@ -201,6 +232,7 @@ const MemoryPlugin: Plugin = {
         '**Good habits:**',
         '- Give memories clear titles ("User prefers dark mode" not "Note 1")',
         '- Use categories: preference, fact, learning, project, identity, decision',
+        '- Search session archives before assuming older conversation context is still in the live chat history',
         '- Check what I already know before storing something new',
         '- When I learn something that corrects old knowledge, update or remove the old memory',
       ].join('\n'))

package/src/lib/server/session-tools/monitor.ts

@@ -8,16 +8,98 @@ import { getPluginManager } from '../plugins'
 import type { Plugin, PluginHooks } from '@/types'
 import { safePath, truncate } from './context'
 import { normalizeToolInputArgs } from './normalize-tool-args'
+import { cancelWatchJob, createWatchJob, getWatchJob, listWatchJobs } from '../watch-jobs'
+import { ensureSessionBrowserProfileId, loadBrowserSessionRecord } from '../browser-state'
+
+type WatchKind = 'time' | 'http' | 'file' | 'task' | 'webhook' | 'page'
+
+async function createDurableWatch(
+  normalized: Record<string, unknown>,
+  bctx: { cwd: string; sessionId?: string; agentId?: string | null },
+  explicitType?: WatchKind,
+) {
+  const watchType = (explicitType || String(normalized.watchType || normalized.type || '').trim().toLowerCase()) as WatchKind
+  if (!watchType) return 'Error: watchType is required.'
+  if (!['time', 'http', 'file', 'task', 'webhook', 'page'].includes(watchType)) {
+    return `Error: Unsupported watchType "${watchType}".`
+  }
+
+  const sessionId = typeof normalized.sessionId === 'string' ? normalized.sessionId : bctx.sessionId
+  const agentId = typeof normalized.agentId === 'string' ? normalized.agentId : (bctx.agentId || undefined)
+  const resumeMessage = String(normalized.resumeMessage || normalized.message || '').trim()
+  if (!resumeMessage) return 'Error: resumeMessage is required.'
+
+  const target = (normalized.target ?? normalized.url ?? normalized.path) as string | undefined
+  const delayMinutes = typeof normalized.delayMinutes === 'number' ? normalized.delayMinutes : undefined
+  const runAt = typeof normalized.runAt === 'number'
+    ? normalized.runAt
+    : delayMinutes !== undefined
+      ? Date.now() + Math.max(0, delayMinutes) * 60_000
+      : undefined
+  const intervalMs = typeof normalized.intervalSec === 'number'
+    ? Math.max(15, normalized.intervalSec) * 1000
+    : typeof normalized.intervalMs === 'number'
+      ? Math.max(15_000, normalized.intervalMs)
+      : undefined
+  const timeoutAt = typeof normalized.timeoutMinutes === 'number'
+    ? Date.now() + Math.max(1, normalized.timeoutMinutes) * 60_000
+    : typeof normalized.timeoutAt === 'number'
+      ? normalized.timeoutAt
+      : undefined
+  const browserProfileId = sessionId ? ensureSessionBrowserProfileId(sessionId).profileId : null
+  const targetPath = watchType === 'file' && target ? safePath(bctx.cwd, target) : target
+  const pageUrl = watchType === 'page' && !target && sessionId
+    ? loadBrowserSessionRecord(sessionId)?.currentUrl || undefined
+    : undefined
+  const pageTarget = target || pageUrl
+  if ((watchType === 'http' || watchType === 'page') && !pageTarget) {
+    return `Error: ${watchType === 'page' ? 'url or active browser page' : 'url'} is required.`
+  }
+
+  const job = await createWatchJob({
+    type: watchType,
+    sessionId: sessionId || null,
+    agentId: agentId || null,
+    createdByAgentId: agentId || null,
+    browserProfileId,
+    description: typeof normalized.description === 'string' ? normalized.description : null,
+    resumeMessage,
+    runAt,
+    intervalMs,
+    timeoutAt,
+    target: {
+      url: watchType === 'http' || watchType === 'page' ? pageTarget : undefined,
+      path: watchType === 'file' ? targetPath : undefined,
+      taskId: watchType === 'task' ? String(normalized.taskId || normalized.id || '') : undefined,
+      webhookId: watchType === 'webhook' ? String(normalized.webhookId || normalized.id || '') : undefined,
+      baselineHash: undefined,
+    },
+    condition: {
+      containsText: typeof normalized.containsText === 'string' ? normalized.containsText : undefined,
+      textGone: typeof normalized.textGone === 'string' ? normalized.textGone : undefined,
+      regex: typeof normalized.regex === 'string' ? normalized.regex : undefined,
+      changed: normalized.changed === true,
+      exists: normalized.exists,
+      status: typeof normalized.status === 'number' ? normalized.status : undefined,
+      statusIn: Array.isArray(normalized.statusIn) ? normalized.statusIn : undefined,
+      event: typeof normalized.event === 'string' ? normalized.event : undefined,
+      threshold: typeof normalized.threshold === 'number' ? normalized.threshold : undefined,
+    },
+  })
+  return JSON.stringify(job, null, 2)
+}
 
 /**
  * Unified Monitoring Logic
  */
-async function executeMonitorAction(args: any, bctx: { cwd: string }) {
+async function executeMonitorAction(args: any, bctx: { cwd: string; sessionId?: string; agentId?: string | null }) {
   const normalized = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
   const action = normalized.action as string | undefined
   const target = (normalized.target ?? normalized.url ?? normalized.path) as string | undefined
   const limit = normalized.limit as number | undefined
   const threshold = normalized.threshold as number | undefined
+  const sessionId = typeof normalized.sessionId === 'string' ? normalized.sessionId : bctx.sessionId
+  const agentId = typeof normalized.agentId === 'string' ? normalized.agentId : (bctx.agentId || undefined)
 
   try {
     switch (action) {
@@ -65,6 +147,7 @@ async function executeMonitorAction(args: any, bctx: { cwd: string }) {
             status: res.status,
             ok: res.ok,
             latency: `${latency}ms`,
+            thresholdExceeded: typeof threshold === 'number' ? latency >= threshold : undefined,
             url
           }, null, 2)
         } catch (err: any) {
@@ -76,6 +159,55 @@ async function executeMonitorAction(args: any, bctx: { cwd: string }) {
         }
       }
 
+      case 'create_watch': {
+        return createDurableWatch(normalized, bctx)
+      }
+
+      case 'wait_until': {
+        return createDurableWatch(normalized, bctx, 'time')
+      }
+
+      case 'wait_for_http': {
+        return createDurableWatch(normalized, bctx, 'http')
+      }
+
+      case 'wait_for_file': {
+        return createDurableWatch(normalized, bctx, 'file')
+      }
+
+      case 'wait_for_task': {
+        return createDurableWatch(normalized, bctx, 'task')
+      }
+
+      case 'wait_for_webhook': {
+        return createDurableWatch(normalized, bctx, 'webhook')
+      }
+
+      case 'wait_for_page_change': {
+        return createDurableWatch(normalized, bctx, 'page')
+      }
+
+      case 'list_watches': {
+        const filterSessionId = normalized.all === true ? undefined : sessionId
+        return JSON.stringify(listWatchJobs({ sessionId: filterSessionId || null }), null, 2)
+      }
+
+      case 'get_watch': {
+        const id = String(normalized.id || '').trim()
+        if (!id) return 'Error: id is required.'
+        const job = getWatchJob(id)
+        if (!job) return `Error: watch job "${id}" not found.`
+        return JSON.stringify(job, null, 2)
+      }
+
+      case 'cancel_watch': {
+        const id = String(normalized.id || '').trim()
+        if (!id) return 'Error: id is required.'
+        const job = cancelWatchJob(id)
+        if (!job) return `Error: watch job "${id}" not found.`
+        return JSON.stringify(job, null, 2)
+      }
+
       default:
         return `Error: Unknown action "${action}"`
     }
@@ -89,22 +221,29 @@ async function executeMonitorAction(args: any, bctx: { cwd: string }) {
  */
 const MonitorPlugin: Plugin = {
   name: 'Core Monitor',
-  description: 'System observability: check resource usage, watch logs, and ping endpoints.',
+  description: 'System observability and durable watch jobs: inspect system state, monitor files/endpoints/tasks, and resume agents when conditions trigger.',
   hooks: {} as PluginHooks,
   tools: [
     {
       name: 'monitor_tool',
-      description: 'Observe system health, log activity, or endpoint availability.',
+      description: 'Observe system health, inspect logs/endpoints, or create durable waits like wait_for_http, wait_for_file, wait_for_webhook, and wait_for_page_change.',
       parameters: {
         type: 'object',
         properties: {
-          action: { type: 'string', enum: ['sys_info', 'watch_log', 'ping'] },
+          action: { type: 'string', enum: ['sys_info', 'watch_log', 'ping', 'create_watch', 'wait_until', 'wait_for_http', 'wait_for_file', 'wait_for_task', 'wait_for_webhook', 'wait_for_page_change', 'list_watches', 'get_watch', 'cancel_watch'] },
           target: { type: 'string', description: 'Log file path (for watch_log) or URL (for ping)' },
-          limit: { type: 'number', description: 'Number of lines or bytes to retrieve' }
+          limit: { type: 'number', description: 'Number of lines or bytes to retrieve' },
+          watchType: { type: 'string', enum: ['time', 'http', 'file', 'task', 'webhook', 'page'] },
+          resumeMessage: { type: 'string', description: 'Message injected when the watch triggers and the agent wakes up.' },
+          regex: { type: 'string', description: 'Regex pattern used by file/page/http watchers.' },
         },
         required: ['action']
       },
-      execute: async (args, context) => executeMonitorAction(args, { cwd: context.session.cwd || process.cwd() })
+      execute: async (args, context) => executeMonitorAction(args, {
+        cwd: context.session.cwd || process.cwd(),
+        sessionId: context.session.id,
+        agentId: context.session.agentId,
+      })
     }
   ]
 }
@@ -115,7 +254,11 @@ export function buildMonitorTools(bctx: ToolBuildContext): StructuredToolInterfa
   if (!bctx.hasPlugin('monitor')) return []
   return [
     tool(
-      async (args) => executeMonitorAction(args, { cwd: bctx.cwd }),
+      async (args) => executeMonitorAction(args, {
+        cwd: bctx.cwd,
+        sessionId: bctx.ctx?.sessionId || undefined,
+        agentId: bctx.ctx?.agentId || undefined,
+      }),
       {
         name: 'monitor_tool',
         description: MonitorPlugin.tools![0].description,

package/src/lib/server/session-tools/normalize-tool-args.ts

@@ -1,4 +1,5 @@
 export type ToolArgsRecord = Record<string, unknown>
+const NESTED_WRAPPER_KEYS = ['input', 'args', 'arguments', 'payload', 'parameters'] as const
 
 function parseRecordCandidate(value: unknown): ToolArgsRecord | null {
   if (!value) return null
@@ -26,22 +27,24 @@ function parseRecordCandidate(value: unknown): ToolArgsRecord | null {
  * as either objects or JSON strings.
  */
 export function normalizeToolInputArgs(rawArgs: ToolArgsRecord): ToolArgsRecord {
-  const nestedSources: Array<ToolArgsRecord | null> = [
-    parseRecordCandidate(rawArgs.input),
-    parseRecordCandidate(rawArgs.args),
-    parseRecordCandidate(rawArgs.arguments),
-    parseRecordCandidate(rawArgs.payload),
-  ]
-
   const normalized: ToolArgsRecord = {}
-  for (const nested of nestedSources) {
-    if (!nested) continue
-    Object.assign(normalized, nested)
-  }
+  const queue: ToolArgsRecord[] = [rawArgs]
+  const visited = new Set<ToolArgsRecord>()
+
+  while (queue.length > 0) {
+    const current = queue.shift()
+    if (!current || visited.has(current)) continue
+    visited.add(current)
 
-  for (const [key, value] of Object.entries(rawArgs)) {
-    if (value === undefined || value === null) continue
-    normalized[key] = value
+    for (const key of NESTED_WRAPPER_KEYS) {
+      const nested = parseRecordCandidate(current[key])
+      if (nested) queue.push(nested)
+    }
+
+    for (const [key, value] of Object.entries(current)) {
+      if (value === undefined || value === null) continue
+      normalized[key] = value
+    }
   }
 
   return normalized