@nuxtagentic/automations 0.0.0-stage → 0.1.0

package/runtime/server/workflows/runner.ts

@@ -0,0 +1,39 @@
+/// <reference types="@cloudflare/workers-types" />
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from 'cloudflare:workers'
+import { createJobContext, type AutomationJob } from '../utils/automation-context'
+import { closeUnfinishedRun, executeAutomation, type DurableStep } from '../utils/automation-engine'
+import { retryTransientFailures } from '../utils/transient-retry'
+
+// Application failures are recorded per agent attempt by the engine, so the
+// platform never replays a step; brief D1 and network interruptions are retried
+// inside it instead.
+const STEP = { retries: { limit: 0, delay: '1 second' }, timeout: '10 minutes' } as const
+
+export class AutomationRunner extends WorkflowEntrypoint<Cloudflare.Env, AutomationJob> {
+  async run(event: WorkflowEvent<AutomationJob>, step: WorkflowStep) {
+    const context = await retryTransientFailures(() =>
+      createJobContext(event.payload, this.env as Record<string, unknown>),
+    )
+    const durable: DurableStep = (name, callback) =>
+      step.do(name, STEP, async () =>
+        JSON.parse(JSON.stringify((await retryTransientFailures(callback)) ?? null)),
+      )
+    let wake = 0
+    try {
+      return await executeAutomation(event.payload, context, durable, async (id) => {
+        await step.waitForEvent(`approval ${id} wake ${wake++}`, {
+          type: `integration-approval-${id}`,
+          timeout: '30 days',
+        })
+      })
+    } catch (cause) {
+      // Close the run's record before the instance errors, so history never shows it running.
+      await durable('close unfinished run', () =>
+        closeUnfinishedRun(event.payload, context, cause),
+      ).catch((closeError: unknown) => {
+        console.error('[automations] Could not close an interrupted run.', closeError)
+      })
+      throw cause
+    }
+  }
+}

package/runtime/shared/agent.ts

@@ -0,0 +1,5 @@
+import type { WorkspaceMetadata } from '@nuxtagentic/prompt/server-contributions'
+export default {
+  excludedModels: ['automationRun', 'automationFolder'],
+  resourceAliases: { automation: ['automation', 'automations', 'workflow', 'workflows'] },
+} satisfies WorkspaceMetadata

package/runtime/shared/automation-run.ts

@@ -0,0 +1,61 @@
+import type { AutomationStep } from './automation'
+
+export type RunStatus = 'queued' | 'running' | 'waiting' | 'succeeded' | 'failed'
+export type DisplayStatus = RunStatus | 'skipped' | 'retry' | undefined
+
+const statusColors: Partial<Record<NonNullable<DisplayStatus>, string>> = {
+  succeeded: 'text-success',
+  failed: 'text-error',
+  retry: 'text-warning',
+  running: 'text-highlighted',
+}
+
+export function getStatusColor(status: DisplayStatus) {
+  return (status && statusColors[status]) || 'text-dimmed'
+}
+
+export function getStepStatus(step: AutomationStep | undefined): DisplayStatus {
+  return step?.status === 'running' && (step.attempt ?? 0) > 1 ? 'retry' : step?.status
+}
+
+export function formatElapsedDuration(
+  start: string | null | undefined,
+  end: string | null | undefined,
+) {
+  if (!start || !end) {
+    return ''
+  }
+  const seconds = (new Date(end).getTime() - new Date(start).getTime()) / 1000
+  return Number.isFinite(seconds) && seconds >= 0 ? `${seconds.toFixed(1)}s` : ''
+}
+
+export function formatStepDuration(step: AutomationStep | undefined) {
+  if (!step) {
+    return ''
+  }
+  const { status, startedAt, finishedAt, logs, at } = step
+  if (status === 'skipped') {
+    return ''
+  }
+  if (status === 'running') {
+    return '…'
+  }
+  if (!startedAt && (logs?.length ?? 0) < 2) {
+    return ''
+  }
+  return formatElapsedDuration(
+    startedAt ?? logs?.[0]?.at ?? at,
+    finishedAt ?? logs?.at(-1)?.at ?? at,
+  )
+}
+
+export function getStepLogs(step: AutomationStep | undefined) {
+  if (!step) {
+    return []
+  }
+  const { status, logs, at, message } = step
+  if (status === 'skipped') {
+    return []
+  }
+  return logs?.length ? logs : [{ at, status, message }]
+}

package/runtime/shared/automation.ts

@@ -0,0 +1,202 @@
+export type AutomationNode = 'trigger' | 'agent' | 'success' | 'error'
+export type AutomationAction = 'none' | 'email' | 'slack' | 'record' | 'webhook' | 'notify'
+export interface AutomationTrigger {
+  kind: 'event' | 'webhook' | 'schedule'
+  event: string
+  slug: string
+  cron?: string
+  timeZone?: string
+}
+export interface AutomationOutcome {
+  action: AutomationAction
+  target: string
+}
+export type AutomationPositions = Record<AutomationNode, { x: number; y: number }>
+export interface AutomationDraft {
+  name: string
+  folder: string
+  active: boolean
+  workspace: string
+  trigger: AutomationTrigger
+  agentId: number
+  instructions: string
+  timeout: number
+  retries: number
+  success: AutomationOutcome
+  failure: AutomationOutcome
+  positions: AutomationPositions
+  /**
+   * Whose connections runs may use: the owner's own plus the workspace's, or
+   * only the workspace's shared ones so the automation never acts as a person.
+   */
+  runAs?: 'owner' | 'workspace'
+}
+export interface AutomationStep {
+  node: AutomationNode
+  status: 'running' | 'succeeded' | 'failed' | 'skipped'
+  at: string
+  message: string
+  summary?: string
+  startedAt?: string
+  finishedAt?: string
+  attempt?: number
+  retryLimit?: number
+  details?: Record<string, string>
+  logs?: {
+    at: string
+    status: AutomationStep['status']
+    message: string
+    level?: 'info' | 'warning' | 'error'
+  }[]
+}
+export const AUTOMATION_POSITIONS: AutomationPositions = {
+  trigger: { x: -140, y: 40 },
+  agent: { x: -140, y: 250 },
+  success: { x: -330, y: 480 },
+  error: { x: 50, y: 480 },
+}
+export const LOCAL_EVENTS = [
+  {
+    id: 'user.created',
+    label: 'A user is created',
+    detail: 'An administrator creates an account.',
+  },
+  {
+    id: 'user.deactivated',
+    label: 'A user is deactivated',
+    detail: 'An administrator disables an account.',
+  },
+  { id: 'file.uploaded', label: 'A file is uploaded', detail: 'A local file finishes uploading.' },
+  {
+    id: 'task.moved',
+    label: 'A task changes status',
+    detail: 'A board card moves to another status.',
+  },
+] as const
+export const SUCCESS_ACTIONS = [
+  {
+    value: 'email',
+    label: 'Send email',
+    icon: 'i-lucide-mail',
+    detail: 'Send the result through your Gmail connection.',
+  },
+  {
+    value: 'slack',
+    label: 'Post to Slack',
+    icon: 'i-lucide-hash',
+    detail: 'Post the result to a connected channel.',
+  },
+  {
+    value: 'record',
+    label: 'Update record',
+    icon: 'i-lucide-database',
+    detail: 'Write the result to a field on the triggering record.',
+  },
+  {
+    value: 'webhook',
+    label: 'Call webhook',
+    icon: 'i-lucide-webhook',
+    detail: 'POST the result to an allowed HTTPS endpoint.',
+  },
+  {
+    value: 'none',
+    label: 'Keep result',
+    icon: 'i-lucide-check',
+    detail: 'Save the result in run history.',
+  },
+] as const
+export const ERROR_ACTIONS = [
+  {
+    value: 'notify',
+    label: 'Notify owner',
+    icon: 'i-lucide-mail',
+    detail: 'Email a failure report through Gmail.',
+  },
+  {
+    value: 'slack',
+    label: 'Post to Slack',
+    icon: 'i-lucide-hash',
+    detail: 'Post a failure alert to a connected channel.',
+  },
+  {
+    value: 'none',
+    label: 'Stop silently',
+    icon: 'i-lucide-circle-stop',
+    detail: 'Record the failure without sending a notification.',
+  },
+] as const
+export function createAutomationDraft(workspace: string, folder = 'Unsorted'): AutomationDraft {
+  return {
+    name: 'Untitled automation',
+    folder,
+    active: false,
+    workspace,
+    trigger: { kind: 'event', event: 'user.created', slug: 'new-signup' },
+    agentId: 0,
+    instructions: 'Use the event payload to complete your task. Return a concise result.',
+    timeout: 30,
+    retries: 2,
+    success: { action: 'none', target: '' },
+    failure: { action: 'none', target: '' },
+    positions: structuredClone(AUTOMATION_POSITIONS),
+    runAs: 'owner',
+  }
+}
+export function getTargetLabel(action: AutomationAction) {
+  return {
+    none: '',
+    email: 'Recipient',
+    notify: 'Owner email',
+    slack: 'Channel',
+    record: 'Field',
+    webhook: 'URL',
+  }[action]
+}
+
+/** The short label for what starts an automation, such as its webhook route or cron schedule. */
+export function describeTrigger(trigger: AutomationTrigger) {
+  switch (trigger.kind) {
+    case 'webhook':
+      return `POST /hooks/${trigger.slug}`
+    case 'schedule':
+      return `${trigger.cron ?? ''} · ${trigger.timeZone ?? ''}`
+    default:
+      return trigger.event
+  }
+}
+
+/** Labels shared by the workspace canvas and embedded examples. */
+export function describeAutomationNodes(
+  draft: AutomationDraft,
+  context: { agentName?: string; eventLabel?: string },
+): Record<AutomationNode, { main: string; sub: string }> {
+  let triggerSource = context.eventLabel ?? 'Connected application event'
+  if (draft.trigger.kind === 'webhook') {
+    triggerSource = 'Authenticated webhook'
+  } else if (draft.trigger.kind === 'schedule') {
+    triggerSource = 'Scheduled run'
+  }
+
+  const successLabel =
+    SUCCESS_ACTIONS.find((action) => action.value === draft.success.action)?.label ?? 'Keep result'
+  const failureLabel =
+    ERROR_ACTIONS.find((action) => action.value === draft.failure.action)?.label ?? 'Stop silently'
+  const errorSummary =
+    draft.retries > 0 ? `Retry ${draft.retries}×, then ${failureLabel.toLowerCase()}` : failureLabel
+
+  return {
+    trigger: { main: describeTrigger(draft.trigger), sub: triggerSource },
+    agent: {
+      main: context.agentName ?? 'Choose an agent',
+      sub: context.agentName ? draft.instructions : 'Select a saved agent and instructions',
+    },
+    success: {
+      main: successLabel,
+      sub: draft.success.target || 'Save the agent result in run history',
+    },
+    error: {
+      main: errorSummary,
+      sub: draft.failure.target || 'Failure is logged in run history',
+    },
+  }
+}

package/runtime/workspace.ts

@@ -0,0 +1,56 @@
+import { computed } from 'vue'
+import type { WorkspaceContribution } from '@nuxtagentic/workspace/runtime/types'
+import type { AgentAction } from '@nuxtagentic/workspace/runtime/shared/agent-actions'
+
+const commands = [
+  ['save-automation', 'Save automation', 'Save this automation.', 'i-lucide-save'],
+  ['test-automation', 'Test run', 'Run this automation with a sample event.', 'i-lucide-play'],
+  [
+    'webhook-automation',
+    'Trigger on a webhook',
+    'Use an authenticated webhook trigger.',
+    'i-lucide-webhook',
+  ],
+  [
+    'retry-automation',
+    'Retry 3 times on error',
+    'Set agent retries to three.',
+    'i-lucide-rotate-cw',
+  ],
+  [
+    'slack-automation',
+    'Post errors to Slack',
+    'Choose a Slack failure notification.',
+    'i-lucide-hash',
+  ],
+] as const
+const actions: AgentAction[] = commands.map(([id, name, description, icon]) => ({
+  id,
+  name,
+  description,
+  icon,
+  available: (context) => context.canRun(id),
+  run: (context) => context.run(id),
+}))
+export const automationsContribution = {
+  id: 'automations',
+  label: 'Automations',
+  icon: 'i-lucide-workflow',
+  selectionKey: 'automation',
+  matchesRoute: (route) => route.path === '/dashboard/automations',
+  navigation: { order: 70, group: 'workspace' },
+  navigationShortcuts: [
+    { label: 'Automations', icon: 'i-lucide-workflow', to: '/dashboard/automations' },
+  ],
+  layout: {
+    navbar: true,
+    hideTitle: true,
+    navbarClass: 'gap-2.5 bg-(--gray-200) px-3 ps-2.5 sm:px-3 sm:ps-2.5',
+    edgeToEdge: true,
+    flat: true,
+    hideExpand: true,
+    ownsDetailAside: true,
+  },
+  usePromptPresentation: () => computed(() => ({ placeholder: 'Describe your automation…' })),
+  actions: { automations: actions },
+} satisfies WorkspaceContribution

package/schema.ts

@@ -0,0 +1,222 @@
+import { model, t } from '@cloudconfig/core'
+import { createAutomationDraft } from './runtime/shared/automation'
+import { nextAgentSchedule } from '@cloudconfig/core/agents/schedules'
+import { syncAutomationSchedule } from './runtime/server/utils/schedule-sync'
+const defaults = createAutomationDraft('personal')
+
+export const automationsModels = {
+  automation: model(
+    {
+      name: t.text().required(),
+      folder: t.text().default('Unsorted'),
+      active: t.boolean().default(false),
+      workspace: t.text().required(),
+      trigger: t.json().default(defaults.trigger),
+      agentId: t.number().default(0),
+      instructions: t.textarea().default(defaults.instructions),
+      timeout: t.number().default(30),
+      retries: t.number().default(2),
+      success: t.json().default(defaults.success),
+      failure: t.json().default(defaults.failure),
+      positions: t.json().default(defaults.positions),
+      runAs: t.select(['owner', 'workspace']).default('owner'),
+      webhookToken: t.text().required().serverOnly(),
+      ownerId: t.number().required().serverOnly(),
+    },
+    {
+      access: {
+        list: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        read: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        create: ({ user }) => !!user,
+        update: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        delete: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+      },
+      hooks: {
+        beforeCreate: ({ user }, input) => ({
+          ...input,
+          ownerId: user!.id,
+          webhookToken: crypto.randomUUID() + crypto.randomUUID(),
+        }),
+        beforeUpdate: ({ user }, input) => ({ ...input, ownerId: user!.id }),
+        afterChange: async ({ user, env }, change) => {
+          if (user) {
+            await syncAutomationSchedule(env, Number(user.id), Number(change.id), change.row)
+          }
+        },
+      },
+      validate: (input, existing) => {
+        const issues: { path: string; message: string }[] = []
+        if (!String(input.name ?? '').trim() || String(input.name).length > 200) {
+          issues.push({
+            path: 'name',
+            message: 'Use an automation name between 1 and 200 characters.',
+          })
+        }
+        if (!String(input.folder ?? '').trim() || String(input.folder).length > 80) {
+          issues.push({ path: 'folder', message: 'Use a folder name between 1 and 80 characters.' })
+        }
+        if (!input.workspace || (existing && input.workspace !== existing.workspace)) {
+          issues.push({
+            path: 'workspace',
+            message: 'Keep this automation in its original workspace.',
+          })
+        }
+        const trigger = input.trigger as Record<string, unknown> | null
+        if (
+          !trigger ||
+          !['event', 'webhook', 'schedule'].includes(String(trigger.kind)) ||
+          (trigger.kind === 'event' && typeof trigger.event !== 'string') ||
+          (trigger.kind === 'webhook' && !/^[a-z0-9-]{1,80}$/.test(String(trigger.slug)))
+        ) {
+          issues.push({
+            path: 'trigger',
+            message:
+              'Choose an event, schedule, or webhook path using lowercase letters, numbers and hyphens.',
+          })
+        }
+        if (trigger?.kind === 'schedule') {
+          try {
+            nextAgentSchedule(String(trigger.cron ?? ''), String(trigger.timeZone ?? ''))
+          } catch {
+            issues.push({
+              path: 'trigger',
+              message:
+                'Use a five-field cron expression and an IANA time zone, such as Europe/Amsterdam.',
+            })
+          }
+        }
+        if (![15, 30, 60].includes(Number(input.timeout))) {
+          issues.push({ path: 'timeout', message: 'Choose a timeout of 15, 30 or 60 seconds.' })
+        }
+        if (
+          !Number.isInteger(input.retries) ||
+          Number(input.retries) < 0 ||
+          Number(input.retries) > 5
+        ) {
+          issues.push({ path: 'retries', message: 'Choose between 0 and 5 retries.' })
+        }
+        if (
+          !Number.isSafeInteger(input.agentId) ||
+          Number(input.agentId) < 0 ||
+          (input.active && !input.agentId)
+        ) {
+          issues.push({
+            path: 'agentId',
+            message: 'Choose an agent before activating this automation.',
+          })
+        }
+        if (String(input.instructions).length > 20000) {
+          issues.push({
+            path: 'instructions',
+            message: 'Use instructions of 20,000 characters or fewer.',
+          })
+        }
+        for (const [field, actions] of [
+          ['success', ['none', 'email', 'slack', 'record', 'webhook']],
+          ['failure', ['none', 'notify', 'slack']],
+        ] as const) {
+          const outcome = input[field] as Record<string, unknown> | null
+          if (
+            !outcome ||
+            !actions.includes(String(outcome.action) as never) ||
+            typeof outcome.target !== 'string' ||
+            outcome.target.length > 2048 ||
+            (outcome.action !== 'none' && !outcome.target.trim())
+          ) {
+            issues.push({ path: field, message: 'Choose an action and enter its destination.' })
+          }
+        }
+        const positions = input.positions as Record<string, { x: number; y: number }> | null
+        if (
+          !positions ||
+          ['trigger', 'agent', 'success', 'error'].some(
+            (node) => !Number.isFinite(positions[node]?.x) || !Number.isFinite(positions[node]?.y),
+          )
+        ) {
+          issues.push({ path: 'positions', message: 'Use valid node positions.' })
+        }
+        return issues
+      },
+    },
+  ),
+  automationFolder: model(
+    {
+      name: t.text().required(),
+      workspace: t.text().required(),
+      ownerId: t.number().required().serverOnly(),
+    },
+    {
+      access: {
+        list: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        read: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        create: ({ user }) => !!user,
+        delete: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+      },
+      hooks: {
+        beforeCreate: ({ user }, input) => ({
+          ...input,
+          name: String(input.name ?? '').trim(),
+          ownerId: user!.id,
+        }),
+      },
+      validate: (input) => {
+        const name = String(input.name ?? '')
+        if (!name || name.length > 80) {
+          return [{ path: 'name', message: 'Use a folder name between 1 and 80 characters.' }]
+        }
+        if (name.toLowerCase() === 'unsorted') {
+          return [{ path: 'name', message: 'Choose a different folder name.' }]
+        }
+        return []
+      },
+    },
+  ),
+  automationRun: model(
+    {
+      automationId: t.number().required(),
+      workspace: t.text().required(),
+      eventId: t.text().required().unique(),
+      status: t.select(['queued', 'running', 'waiting', 'succeeded', 'failed']).default('queued'),
+      payload: t.json().required(),
+      steps: t.json().default([]),
+      output: t.textarea().default(''),
+      error: t.textarea().default(''),
+      attempts: t.number().default(0),
+      startedAt: t.datetime(),
+      finishedAt: t.datetime(),
+      snapshot: t.json().required().serverOnly(),
+      journal: t.json().default({}).serverOnly(),
+      ownerId: t.number().required().serverOnly(),
+    },
+    {
+      access: {
+        list: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        read: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        create: ({ user, input }) => !!user && input?.ownerId === user.id,
+        update: ({ user, input, where }) =>
+          user && input?.ownerId === user.id ? where('ownerId', 'eq', user.id) : false,
+      },
+    },
+  ),
+  // One row per journaled model or tool call, so a long run never outgrows D1's row limit.
+  automationRunReceipt: model(
+    {
+      runId: t.number().required(),
+      key: t.text().required().unique(),
+      status: t.select(['started', 'completed']).default('started').serverOnly(),
+      value: t.json().serverOnly(),
+      ownerId: t.number().required().serverOnly(),
+    },
+    {
+      // Writes require the server-only owner, so only the automation engine records receipts.
+      access: {
+        list: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        read: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        create: ({ user, input }) => !!user && input?.ownerId === user.id,
+        update: ({ user, input, where }) =>
+          user && input?.ownerId === user.id ? where('ownerId', 'eq', user.id) : false,
+      },
+    },
+  ),
+}
+export type AutomationsConfig = { models: typeof automationsModels }

package/server.ts

@@ -0,0 +1,2 @@
+/** Scheduled automation dispatch for a CloudConfig agent host. */
+export { fireAutomationSchedule } from './runtime/server/utils/automation-schedule'

package/workflow.ts

@@ -0,0 +1,2 @@
+/** Cloudflare Workflow entry point. Import only from a Worker entry adapter. */
+export { AutomationRunner } from './runtime/server/workflows/runner'