@nuxtagentic/automations 0.0.0-stage → 0.1.0

package/runtime/server/utils/automation-engine.ts

@@ -0,0 +1,697 @@
+import type { AgentDefinition } from '@cloudconfig/core/agents'
+import { CloudConfigClientError } from '@cloudconfig/core/client'
+import { getFieldSpec } from '@cloudconfig/core'
+import { createServerClient } from '@cloudconfig/core/server'
+import {
+  actorOf,
+  backendConfig,
+  listGrantedTools,
+  OwnerLeftError,
+  performIntegrationAction,
+  type IntegrationServiceContext,
+} from '@nuxtagentic/integrations/runtime/server/utils/integration-context'
+import { limitToolResult } from '@nuxtagentic/agents/runtime/server/utils/tool-result'
+import { isWorkspaceModuleInstalled } from '@nuxtagentic/workspace/runtime/shared/modules'
+import {
+  type AutomationDraft,
+  type AutomationNode,
+  type AutomationOutcome,
+  type AutomationStep,
+  SUCCESS_ACTIONS,
+  ERROR_ACTIONS,
+  describeTrigger,
+} from '../../shared/automation'
+import type { createJobContext, AutomationJob } from './automation-context'
+import { runSavedAgent } from './agent-runner'
+
+type Context = Awaited<ReturnType<typeof createJobContext>>
+class PendingAutomationApproval extends Error {}
+class InterruptedTool extends Error {}
+export type DurableStep = <T>(name: string, callback: () => Promise<T>) => Promise<T>
+export type ApprovalWait = (id: number) => Promise<void>
+export interface RunSnapshot {
+  automation: AutomationDraft
+  agent: AgentDefinition
+  managed: boolean
+  integrationCallStarted?: boolean
+}
+function errorMessage(cause: unknown) {
+  if (cause instanceof CloudConfigClientError && cause.issues.length) {
+    return cause.issues.map((issue) => `${issue.path}: ${issue.message}`).join('; ')
+  }
+  if (!(cause instanceof Error)) {
+    return 'The automation could not complete.'
+  }
+  if (cause.name === 'TimeoutError' || cause.name === 'AbortError') {
+    return 'The agent exceeded its configured timeout.'
+  }
+  return cause.message
+}
+
+function describeTriggerReceipt(trigger: AutomationDraft['trigger']) {
+  switch (trigger.kind) {
+    case 'webhook':
+      return 'Webhook received.'
+    case 'schedule':
+      return 'Scheduled run received.'
+    default:
+      return `Received ${trigger.event}.`
+  }
+}
+
+function getLogLevel(status: AutomationStep['status'], message: string) {
+  if (status === 'failed') {
+    return 'error'
+  }
+  return message.includes(' failed:') ? 'warning' : 'info'
+}
+
+const localExecutions = new Map<string, ReturnType<typeof runAutomation>>()
+export async function executeAutomation(
+  job: AutomationJob,
+  context: Context,
+  step: DurableStep = async (_name, callback) => callback(),
+  waitForApproval?: ApprovalWait,
+) {
+  // Workflows serialize a deployed run. Node approval retries need the same protection.
+  if (context.env) {
+    return runAutomation(job, context, step, waitForApproval)
+  }
+  const key = `${context.database.id}:${job.ownerId}:${job.runId}`
+  const active = localExecutions.get(key)
+  if (active) {
+    return active
+  }
+  const task = runAutomation(job, context, step, waitForApproval)
+  localExecutions.set(key, task)
+  try {
+    return await task
+  } finally {
+    localExecutions.delete(key)
+  }
+}
+
+/** A run must never stay queued, running or waiting after its execution has stopped. */
+export async function closeUnfinishedRun(job: AutomationJob, context: Context, cause: unknown) {
+  const run = await context.api.automationRun.get(job.runId)
+  if (['succeeded', 'failed'].includes(run.status)) {
+    return run.status
+  }
+  await context.api.automationRun.update(run.id, {
+    ownerId: job.ownerId,
+    status: 'failed',
+    error: `Execution stopped unexpectedly: ${errorMessage(cause)}`,
+    finishedAt: new Date().toISOString(),
+  })
+  return 'failed'
+}
+
+/** The integration view of a run: its owner, workspace and run-as choice. */
+function integrationContext(
+  job: AutomationJob,
+  context: Context,
+  runAs?: 'owner' | 'workspace',
+): IntegrationServiceContext {
+  return {
+    ownerId: job.ownerId,
+    workspace: job.workspace,
+    env: context.env,
+    database: context.database,
+    request: context.request,
+    ...(runAs ? { runAs } : {}),
+  }
+}
+
+async function runAutomation(
+  job: AutomationJob,
+  context: Context,
+  step: DurableStep = async (_name, callback) => callback(),
+  waitForApproval?: ApprovalWait,
+) {
+  const run = await step('load run', () => context.api.automationRun.get(job.runId))
+  if (['succeeded', 'failed'].includes(run.status)) {
+    return { status: run.status, runId: run.id }
+  }
+  const snapshot = run.snapshot as RunSnapshot
+  const automation = snapshot.automation
+  const integrations = integrationContext(job, context, automation.runAs)
+  // A run acts as its owner; once they leave the workspace it must not act at all.
+  const ownerPresent = await step('check owner membership', async () => {
+    try {
+      await actorOf(integrations)
+      return true
+    } catch (cause) {
+      if (cause instanceof OwnerLeftError) {
+        return false
+      }
+      throw cause
+    }
+  })
+  if (!ownerPresent) {
+    await step('pause automation of a departed owner', async () => {
+      await context.api.automation
+        .update(run.automationId, { active: false })
+        .catch(() => undefined)
+      await context.api.automationRun.update(run.id, {
+        ownerId: job.ownerId,
+        status: 'failed',
+        error:
+          'The owner left this workspace, so the automation was paused. A member can take it over by recreating it.',
+        finishedAt: new Date().toISOString(),
+      })
+      return true
+    })
+    return { status: 'failed', runId: run.id }
+  }
+  let output = ''
+  let failure = ''
+  let attempts = 0
+  let modulesAvailable = false
+  const source = describeTrigger(automation.trigger)
+  const agentName = snapshot.agent.markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || 'Agent'
+  function stepSummary(node: AutomationNode) {
+    if (node === 'trigger') {
+      return source
+    }
+    if (node === 'agent') {
+      return agentName
+    }
+    const action = node === 'success' ? automation.success : automation.failure
+    const label =
+      (node === 'success' ? SUCCESS_ACTIONS : ERROR_ACTIONS).find(
+        (entry) => entry.value === action.action,
+      )?.label ?? action.action
+    return `${label}${action.target ? ` → ${action.target}` : ''}`
+  }
+  function stepDetails(node: AutomationNode): AutomationStep['details'] {
+    if (node === 'trigger') {
+      return { 'Event ID': run.eventId }
+    }
+    if (node !== 'agent') {
+      return { Action: stepSummary(node) }
+    }
+    const { agent } = snapshot
+    const enabledTools = agent.tools.filter((tool) => tool.enabled).map((tool) => tool.name)
+    return {
+      Provider: agent.provider,
+      Model: agent.model,
+      // Deployed Workers can only call provider APIs; local CLI runtimes exist in dev only.
+      Runtime: import.meta.dev ? (agent.runtime ?? 'api') : 'api',
+      ...(agent.localModel ? { 'Local model': agent.localModel } : {}),
+      Timeout: `${automation.timeout}s per model or tool call`,
+      Attempts: String(attempts),
+      Instructions: automation.instructions,
+      ...(enabledTools.length ? { Tools: enabledTools.join(', ') } : {}),
+    }
+  }
+  async function mark(node: AutomationNode, status: AutomationStep['status'], message: string) {
+    const current = await context.api.automationRun.get(run.id)
+    const steps = current.steps as AutomationStep[]
+    const existing = steps.findIndex((item) => item.node === node)
+    const at = new Date().toISOString()
+    const previous = existing === -1 ? undefined : steps[existing]
+    const entry: AutomationStep = {
+      node,
+      status,
+      message,
+      at,
+      summary: stepSummary(node),
+      startedAt: previous?.startedAt ?? at,
+      ...(status === 'running' ? {} : { finishedAt: at }),
+      ...(node === 'agent' ? { attempt: attempts, retryLimit: automation.retries } : {}),
+      details: stepDetails(node),
+      logs: [
+        ...(previous?.logs ?? []),
+        {
+          at,
+          status,
+          message,
+          level: getLogLevel(status, message),
+        },
+      ],
+    }
+    if (existing === -1) {
+      steps.push(entry)
+    } else {
+      steps[existing] = entry
+    }
+    await context.api.automationRun.update(run.id, { ownerId: job.ownerId, steps: [...steps] })
+    return entry
+  }
+  await step('start run', async () => {
+    await context.api.automationRun.update(run.id, {
+      ownerId: job.ownerId,
+      status: 'running',
+      startedAt: new Date().toISOString(),
+    })
+    return mark('trigger', 'succeeded', describeTriggerReceipt(automation.trigger))
+  })
+  // D1 also records dispatch before external I/O. Workflow completion alone
+  // cannot cover a crash between an external write and committing its result.
+  // Each receipt is its own row, so long runs never outgrow D1's row limit.
+  type Receipt = { status: 'started' | 'completed'; value?: unknown }
+  async function journal<T>(
+    name: string,
+    callback: () => Promise<T>,
+    external = false,
+  ): Promise<T> {
+    return step(name, async () => {
+      const key = `${run.id}:${name}`
+      const current = await context.api.automationRun.get(run.id)
+      const stored = await context.api.automationRunReceipt.list({
+        pageSize: 1,
+        filters: {
+          type: 'group',
+          logic: 'and',
+          children: [{ type: 'condition', field: 'key', operator: 'eq', value: key }],
+        },
+      })
+      // Runs started before receipts moved out of the run row keep their journal.
+      const legacy = (current.journal as Record<string, Receipt> | null)?.[name]
+      const receipt = (stored.data[0] as Receipt | undefined) ?? legacy
+      if (receipt?.status === 'completed') {
+        return receipt.value as T
+      }
+      if (receipt) {
+        throw new InterruptedTool(
+          'A tool call was interrupted after dispatch. Check its external result before retrying in a new run.',
+        )
+      }
+      let started: number | undefined
+      if (external) {
+        started = (
+          await context.api.automationRunReceipt.create({
+            runId: run.id,
+            key,
+            status: 'started',
+            ownerId: job.ownerId,
+          })
+        ).id
+        if (!(current.snapshot as RunSnapshot).integrationCallStarted) {
+          await context.api.automationRun.update(run.id, {
+            ownerId: job.ownerId,
+            snapshot: { ...(current.snapshot as RunSnapshot), integrationCallStarted: true },
+          })
+        }
+      }
+      const value = (await callback()) ?? null
+      const completed = { status: 'completed' as const, value, ownerId: job.ownerId }
+      if (started) {
+        await context.api.automationRunReceipt.update(started, completed)
+      } else {
+        await context.api.automationRunReceipt.create({ runId: run.id, key, ...completed })
+      }
+      return value as T
+    })
+  }
+  async function approvedResult(result: unknown): Promise<unknown> {
+    if (
+      !result ||
+      typeof result !== 'object' ||
+      !('approvalRequired' in result) ||
+      !('approvalId' in result)
+    ) {
+      return result
+    }
+    const id = Number(result.approvalId)
+    await context.api.automationRun.update(run.id, { ownerId: job.ownerId, status: 'waiting' })
+    for (let wake = 0; wake < 10; wake++) {
+      const approval = await context.api.integrationApproval.get(id)
+      if (approval.status === 'completed') {
+        await context.api.automationRun.update(run.id, { ownerId: job.ownerId, status: 'running' })
+        return limitToolResult(approval.result)
+      }
+      if (approval.status === 'rejected' || approval.status === 'failed') {
+        throw new Error(`The integration action was ${approval.status}.`)
+      }
+      if (!waitForApproval) {
+        throw new PendingAutomationApproval('Approve this action in Integrations.')
+      }
+      await waitForApproval(id)
+    }
+    throw new Error('The integration approval did not complete.')
+  }
+  try {
+    modulesAvailable = await step('check modules', async () => {
+      if (!snapshot.managed) {
+        return true
+      }
+      const installations = await context.api.workspaceInstallation.list({
+        pageSize: 1,
+        filters: {
+          type: 'group',
+          logic: 'and',
+          children: [
+            { type: 'condition', field: 'workspace', operator: 'eq', value: job.workspace },
+          ],
+        },
+      })
+      const installed = installations.data[0]?.installed as string[] | undefined
+      if (!isWorkspaceModuleInstalled('agents', installed)) {
+        throw new Error('Install Agents from Modules before running this automation.')
+      }
+      return true
+    })
+    if (job.forceError) {
+      throw new Error('Error path test requested.')
+    }
+    const tools = await step('load agent tools', async () => {
+      const wanted = snapshot.agent.tools.some((tool) => tool.enabled)
+      const available = wanted ? await listGrantedTools(integrations) : []
+      return snapshot.agent.tools
+        .filter((tool) => tool.enabled && snapshot.agent.toolChoice !== 'none')
+        .map((tool) => {
+          const action = available.find((entry) => entry.name === tool.name)
+          if (!action) {
+            throw new Error(
+              `Tool ${tool.name} has no connected handler or permission. Add an available integration tool, or disable this tool.`,
+            )
+          }
+          return {
+            name: action.name,
+            description: tool.description || action.description,
+            parameters: action.parameters,
+            provider: action.provider,
+            action: action.action,
+            bindingId: action.bindingId,
+          }
+        })
+    })
+    for (let attempt = 0; attempt <= automation.retries; attempt++) {
+      attempts = attempt + 1
+      try {
+        await step(`start agent attempt ${attempts}`, async () => {
+          await context.api.automationRun.update(run.id, { ownerId: job.ownerId, attempts })
+          return mark('agent', 'running', `Attempt ${attempts}`)
+        })
+        output = await runSavedAgent({
+          agent: snapshot.agent,
+          instructions: automation.instructions,
+          payload: run.payload,
+          keys: context.keys,
+          tools,
+          // A fresh deadline per call; Workflow approval waits must not consume it.
+          timeoutMs: automation.timeout * 1000,
+          runId: `automation-${run.id}`,
+          checkpoint: (name, callback) => journal(`attempt ${attempts} ${name}`, callback),
+          callTool: async (name, input, call) => {
+            const tool = tools.find((entry) => entry.name === name)
+            if (!tool) {
+              throw new Error('The agent requested a tool it has not been granted.')
+            }
+            const result = await journal(
+              `attempt ${attempts} tool ${call.callId}`,
+              async () =>
+                limitToolResult(
+                  await performIntegrationAction(
+                    integrations,
+                    {
+                      provider: tool.provider,
+                      action: tool.action,
+                      input,
+                      bindingId: tool.bindingId,
+                    },
+                    {
+                      signal: AbortSignal.timeout(automation.timeout * 1000),
+                      idempotencyKey: call.idempotencyKey,
+                      continuation: {
+                        workflowId: `automation-${run.id}`,
+                        automationRunId: run.id,
+                        workspace: job.workspace,
+                      },
+                    },
+                  ),
+                ),
+              true,
+            )
+            return approvedResult(result)
+          },
+        })
+        break
+      } catch (cause) {
+        if (cause instanceof PendingAutomationApproval || cause instanceof InterruptedTool) {
+          throw cause
+        }
+        await step(`record agent attempt ${attempts} failure`, () =>
+          mark('agent', 'running', `Attempt ${attempts} failed: ${errorMessage(cause)}`),
+        )
+        const integrationCallStarted = await step(`retry policy ${attempts}`, async () => {
+          const current = await context.api.automationRun.get(run.id)
+          return !!(current.snapshot as RunSnapshot).integrationCallStarted
+        })
+        if (attempt === automation.retries || integrationCallStarted) {
+          throw cause
+        }
+      }
+    }
+    await step('agent result', async () => {
+      await context.api.automationRun.update(run.id, { ownerId: job.ownerId, output })
+      return mark(
+        'agent',
+        'succeeded',
+        `Completed in ${attempts} ${attempts === 1 ? 'attempt' : 'attempts'}.`,
+      )
+    })
+    await step('start success action', () =>
+      mark('success', 'running', 'Applying the success action.'),
+    )
+    const successResult = await journal(
+      'success action dispatch',
+      () =>
+        outcome(context, automation.success, {
+          result: { payload: run.payload, output, error: '', runId: run.id, name: automation.name },
+          job,
+          runAs: automation.runAs,
+        }),
+      true,
+    )
+    await approvedResult(successResult)
+    await step('finish success action', () =>
+      mark(
+        'success',
+        'succeeded',
+        automation.success.action === 'none' ? 'Result saved.' : 'Action completed.',
+      ),
+    )
+    await step('skip error action', () => mark('error', 'skipped', 'No failure.'))
+  } catch (cause) {
+    if (cause instanceof PendingAutomationApproval) {
+      return { status: 'waiting', runId: run.id }
+    }
+    failure = errorMessage(cause)
+    await step('record failure', async () => {
+      if (!output) {
+        await mark('agent', 'failed', failure)
+        await mark('success', 'skipped', 'Agent failed.')
+      } else {
+        await mark('success', 'failed', failure)
+      }
+      return failure
+    })
+    try {
+      if (!modulesAvailable) {
+        await step('skip failure action', () =>
+          mark('error', 'skipped', 'A required module was removed.'),
+        )
+      } else {
+        await step('start failure action', () =>
+          mark('error', 'running', 'Applying the failure action.'),
+        )
+        const failureResult = await journal(
+          'failure action dispatch',
+          () =>
+            outcome(context, automation.failure, {
+              result: {
+                payload: run.payload,
+                output,
+                error: failure,
+                runId: run.id,
+                name: automation.name,
+              },
+              job,
+              runAs: automation.runAs,
+            }),
+          true,
+        )
+        await approvedResult(failureResult)
+        await step('finish failure action', () =>
+          mark(
+            'error',
+            'succeeded',
+            automation.failure.action === 'none' ? 'Failure recorded.' : 'Notification sent.',
+          ),
+        )
+      }
+    } catch (notificationError) {
+      if (notificationError instanceof PendingAutomationApproval) {
+        return { status: 'waiting', runId: run.id }
+      }
+      failure += ` Notification failed: ${errorMessage(notificationError)}`
+      await step('record notification failure', () =>
+        mark('error', 'failed', errorMessage(notificationError)),
+      )
+    }
+  }
+  const status = failure ? 'failed' : 'succeeded'
+  await step('finish run', () =>
+    context.api.automationRun.update(run.id, {
+      ownerId: job.ownerId,
+      status,
+      output,
+      error: failure,
+      attempts,
+      finishedAt: new Date().toISOString(),
+    }),
+  )
+  return { status, runId: run.id }
+}
+
+async function outcome(
+  context: Context,
+  action: AutomationOutcome,
+  {
+    result,
+    job,
+    runAs,
+  }: {
+    result: { payload: unknown; output: string; error: string; runId: number; name: string }
+    job: AutomationJob
+    runAs?: 'owner' | 'workspace'
+  },
+) {
+  const { action: actionKind, target: targetTemplate } = action
+  const { payload, output, error, runId, name } = result
+  if (actionKind === 'none') {
+    return
+  }
+  const text = error ? `Automation ${name} failed.\n\n${error}\n\nRun: ${runId}` : output
+  const target = targetTemplate.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_match, path: string) =>
+    String(atPath(payload, path) ?? ''),
+  )
+  if (actionKind === 'email' || actionKind === 'notify') {
+    const recipient = /^(user|payload)\./.test(target)
+      ? String(atPath(payload, target.replace(/^payload\./, '')) ?? '')
+      : target
+    if (!recipient || !recipient.includes('@')) {
+      throw new Error('Set a recipient email address, or a payload path such as user.email.')
+    }
+    return performIntegrationAction(
+      integrationContext(job, context, runAs),
+      {
+        provider: 'gmail',
+        action: 'send_email',
+        input: {
+          body: {
+            to: recipient,
+            subject: error ? `${name} failed` : name,
+            text,
+          },
+        },
+      },
+      {
+        idempotencyKey: `automation-${runId}-${error ? 'failure' : 'success'}`,
+        continuation: {
+          workflowId: `automation-${runId}`,
+          automationRunId: runId,
+          workspace: job.workspace,
+        },
+      },
+    )
+  } else if (actionKind === 'slack') {
+    return performIntegrationAction(
+      integrationContext(job, context, runAs),
+      {
+        provider: 'slack',
+        action: 'post_messages',
+        input: {
+          body: { channel: target, text },
+        },
+      },
+      {
+        idempotencyKey: `automation-${runId}-${error ? 'failure' : 'success'}`,
+        continuation: {
+          workflowId: `automation-${runId}`,
+          automationRunId: runId,
+          workspace: job.workspace,
+        },
+      },
+    )
+  } else if (actionKind === 'webhook') {
+    const url = new URL(target)
+    const allowed = String(
+      context.env?.NUXT_INTEGRATIONS_WEBHOOK_ORIGINS ??
+        process.env.NUXT_INTEGRATIONS_WEBHOOK_ORIGINS ??
+        '',
+    )
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean)
+    if (
+      url.protocol !== 'https:' ||
+      url.username ||
+      url.password ||
+      !allowed.includes(url.origin)
+    ) {
+      throw new Error(
+        'Add this HTTPS origin to NUXT_INTEGRATIONS_WEBHOOK_ORIGINS before calling it.',
+      )
+    }
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Idempotency-Key': `automation-${runId}`,
+      },
+      body: JSON.stringify(result),
+      signal: AbortSignal.timeout(15000),
+      redirect: 'manual',
+    })
+    await response.body?.cancel()
+    if (!response.ok) {
+      throw new Error(`The result webhook returned ${response.status}.`)
+    }
+  } else {
+    const recordPayload = payload as { record?: { model?: string; id?: number } }
+    const record = recordPayload?.record
+    const model = record?.model ?? ''
+    const spec = backendConfig.models[model]
+    if (
+      !record?.id ||
+      !spec ||
+      !spec.fields[target] ||
+      getFieldSpec(spec.fields[target]!).serverOnly ||
+      target === 'id' ||
+      target.endsWith('Id') ||
+      [
+        'automation',
+        'automationRun',
+        'integrationConnection',
+        'integrationApproval',
+        'workspaceInstallation',
+        'agent',
+      ].includes(model)
+    ) {
+      throw new Error(
+        'Use an editable field on the triggering record. The payload must include record: { model, id }.',
+      )
+    }
+    // The canonical server client still applies the model's ownership, validation and hooks.
+    const api = createServerClient(
+      backendConfig,
+      { env: context.env, request: context.request },
+      { db: context.database, getUser: () => ({ id: job.ownerId }) },
+    )
+    await api[model]!.update(record.id, { [target]: output })
+  }
+}
+function atPath(value: unknown, path: string): unknown {
+  return path
+    .split('.')
+    .reduce<unknown>(
+      (entry, key) =>
+        entry && typeof entry === 'object' && Object.hasOwn(entry, key)
+          ? (entry as Record<string, unknown>)[key]
+          : undefined,
+      value,
+    )
+}