@nuxtagentic/automations 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+Proprietary software. All rights reserved.
+
+Use of Nuxt Agentic packages and starter materials is governed by the applicable
+commercial agreement supplied with a purchase. This repository does not grant
+an open-source license or permission to redistribute the packages as a competing
+template or module library.
+
+Third-party dependencies retain their respective licenses. This notice does not
+replace or modify those licenses.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# Automations
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Schedules use five-field cron and an IANA time zone (for example,
+`0 9 * * 1-5` in `Europe/Amsterdam`). Saving an active scheduled automation
+sets its durable alarm. Editing, pausing or deleting reschedules or cancels it
+through the CloudConfig model hook, including writes from MCP and server SDKs.
+The callback reloads the automation and deduplicates the scheduled timestamp
+before starting a run. Schedules go through CloudConfig's agent platform:
+durable alarms on Cloudflare, and in-process timers that end with the server
+in Node development.
+
+Provider rounds and individual tools checkpoint separately. Integration tools
+recheck current permissions at dispatch. Approval-required tools and outcomes
+pause the run until the owner approves or rejects in Integrations. Cloudflare
+Workflows wake on an approval event and read the stored approval result; local
+runs resume through the authenticated resume endpoint. Results are only marked
+successful after approval and the actual action finish. Completed tools replay
+from receipts. Interrupted external calls stop for review to avoid duplicate
+writes. A waiting approval expires after 30 days in Cloudflare.
+
+**Automations** is a core feature, always available from the dashboard sidebar at
+`/dashboard/automations`.
+Integrations and Agents are also always available. Configure a saved agent in **Agents**.
+Name the automation draft, select a trigger and agent,
+then configure the success and error nodes. Changes save automatically after a
+short pause, including names and node positions. **Save automation** in the Test run
+menu (⌘/Ctrl Enter) saves
+immediately. **Active** enables event delivery. New drafts start paused. The inner sidebar
+organizes automations into searchable, collapsible folders, with a **+** menu for
+new automations and folders. The sidebar header closes the folder list; the button
+over the canvas reopens it. Edit the automation name beside Automations in the navbar. Open the menu beside **Test run**
+and choose **Delete automation** to remove the current automation. Right-click a
+folder to delete it; its automations remain
+available outside folders. Switching automations or leaving the page saves pending
+edits first. Save failures keep the draft visible so you can correct it and retry.
+Activation, Runs, zoom and test controls sit on the right of the dashboard navbar.
+
+Dragging a node changes its saved position. Alignment guides appear near other
+nodes' centers and edges, snapping the dragged node into exact alignment. Drag the
+background to pan; use the zoom controls or Ctrl/Cmd + wheel to zoom. Arrow keys
+move a focused node. Selection,
+pan, zoom, the current folder and the current run live in the URL. Pointer movement
+is batched into animation frames locally; node positions commit when a drag ends,
+and the view syncs to the URL after the interaction. Escape closes the inspector.
+The prompt supports Save automation, Test run, Trigger on a webhook, Retry 3 times
+on error, and Post errors to Slack.
+
+## First run
+
+Create a saved agent in Agents and choose its provider/model. Configure only the
+key for the provider you use:
+
+| Provider  | Server environment variable |
+| --------- | --------------------------- |
+| OpenAI    | `NUXT_OPENAI_API_KEY`       |
+| Anthropic | `NUXT_ANTHROPIC_API_KEY`    |
+| Google AI | `NUXT_GOOGLE_AI_API_KEY`    |
+
+The module also accepts `NUXT_AUTOMATIONS_OPENAI_API_KEY`,
+`NUXT_AUTOMATIONS_ANTHROPIC_API_KEY` and `NUXT_AUTOMATIONS_GOOGLE_AI_API_KEY` as
+dedicated overrides. Add the selected variable to `deploy.secrets` when deploying
+through CloudConfig. Match the agent's model ID to its provider account. Draft
+agents can be tested; automatic event delivery requires an active agent.
+
+The agent's [runtime picker](../agents/README.md) also supports local Codex CLI
+and Claude Code execution during localhost development, using their saved login
+and selected local model. The same agent retains a separate production API
+provider/model. Deployed runs always use that API configuration. The
+`NUXT_AGENTS_*` keys are supported alongside the existing variables above.
+
+Start with **Keep result** and **Stop silently**: no third-party connection is
+needed for a useful agent run. Connect services when you need actions. Add allowed
+integration tools in the agent's Tools drawer. Test runs execute the real agent
+and configured actions; the split-button menu edits the sample payload, tests the
+error path and saves the draft. **Runs** opens the right-hand history panel.
+Select a run to see its input, response or error, source, timing and expandable step logs. New runs retain the agent model, instructions, attempts and actions used at execution time. Re-run with this input starts another test. Escape returns to the run list, then closes the panel. History and run selection live in the URL. Results, failures, attempts and node outcomes are stored in CloudConfig. No success result is simulated.
+
+## Outcomes and retries
+
+- **Send email / Notify owner:** connect Gmail and allow Send email. Use a recipient
+  address, `user.email`, or a template such as `{{ customer.email }}`.
+- **Post to Slack:** connect Slack, allow Post messages and enter the channel ID.
+- **Update record:** enter a writable field name. Event payloads identify the
+  record with `{ "record": { "model": "kanbanCard", "id": 42 } }`. The canonical
+  CloudConfig client enforces ownership, validation and hooks. Private fields,
+  relations and automation/security records cannot be changed by this outcome.
+- **Call webhook:** enter an HTTPS URL and allow its exact origin in the comma-
+  separated `NUXT_INTEGRATIONS_WEBHOOK_ORIGINS` server setting. `pnpm deploy` pushes
+  it from `.env` when set (it is an optional deploy secret). Requests contain the
+  payload, output, error, run ID and name, plus an Idempotency-Key header.
+
+Agent retries are bounded to 0–5, with a fresh configured timeout for each model
+or integration tool call. Approval waits do not consume this timeout.
+After starting an integration tool call, a failed agent attempt goes to the error
+branch instead of repeating provider writes. Outcome actions are not automatically
+retried. Receivers should honor idempotency keys where available; external APIs
+cannot universally guarantee exactly-once delivery.
+
+Each model and tool call is journaled as its own `automationRunReceipt` row, so a
+long run never outgrows D1's 2 MB row limit. Integration results larger than
+256 KB reach the agent as a truncated preview with a hint to narrow the request,
+which also keeps every Workflow step under its 1 MiB limit.
+
+## Maintenance
+
+On Cloudflare, the Worker's cron trigger (`*/15 * * * *` in `wrangler.jsonc`) runs a
+bounded, idempotent maintenance job:
+
+- **Lost schedules.** When an active scheduled automation has no run for its last
+  due time (ten minutes of grace), its alarm is re-armed. An occurrence missed
+  within the last hour also runs late, under the event ID the alarm would have used.
+- **Orphaned runs.** A run left queued, running or waiting for fifteen minutes is
+  checked against its Workflow instance. If the instance errored, was terminated
+  or no longer exists, the run is closed as failed with the reason.
+- **Retention.** Replay receipts are removed a day after their run finishes. Set
+  `NUXT_AUTOMATIONS_RUN_RETENTION_DAYS` to also delete finished runs older than
+  that many days; it is unset by default, which keeps all history.
+
+## Webhooks and agent hosts
+
+Choose Webhook, save, then copy the generated endpoint. Activate the automation
+and its agent before sending events. POST JSON with a unique `Idempotency-Key`
+header; repeated keys return the existing run. The endpoint is a secret capability,
+scoped to its owner and automation. Request bodies are limited to 100 KB.
+
+Authenticated CloudConfig REST/MCP tools manage `automation` records and read
+`automationRun` history. Runtime commands use an authenticated request transport:
+
+```ts
+import { createAutomationCommands } from '@nuxtagentic/automations/client'
+
+const automations = createAutomationCommands(useRequestFetch())
+const run = await automations.run(automationId, { user: { email: 'you@company.com' } })
+await automations.emit(
+  'task.moved',
+  {
+    record: { model: 'kanbanCard', id: cardId },
+    data: { status: 'done' },
+  },
+  crypto.randomUUID(),
+)
+```
+
+CloudConfig remains the source of truth for records; helpers only call custom
+execution commands. A connected service's Event endpoint accepts normalized
+provider events without browser cookies. Local HTTP account creation/deactivation,
+file uploads and board status changes dispatch workspace events after a successful
+response. Imports, direct server SDK writes, MCP mutations and other application
+code should explicitly call `emit` after their mutation succeeds. User-created
+events refer to administrator-created accounts; social sign-up needs an auth hook
+or explicit event emitter in the host.
+
+For a process-local MCP agent, embed `createMcpServer` with an explicit `principal`
+whose numeric ID matches the owning account; network MCP needs per-request
+authentication. The default anonymous `cloudconfig mcp` process cannot access
+these private records. Runtime commands also require that account's authenticated
+transport, or the saved automation's secret webhook endpoint.
+
+## Deployment and core registration
+
+Nuxt development runs asynchronously through Nitro's `waitUntil`. Cloudflare
+deployments use the `AUTOMATION_RUNNER` Workflows binding and the exported
+`AutomationRunner` class, so executions survive the HTTP request. Declare its
+entry, class, binding and name in `deploy.workflows` in `cloud.config.ts`.
+The CloudConfig Nuxt module exports the class and the CLI reconciles the root
+Wrangler binding. Scheduled triggers also require the agent host declared in
+`deploy.agents`, whose `scheduled` callback launches the automation. Deploy with
+`pnpm deploy`.
+
+Provision `automationsModels` and `integrationsModels` in the host's
+`cloud.config.ts`, generate/review migrations, then migrate. Agents, Integrations and
+Automations register without catalog entries and stay active for every workspace,
+including existing saved installation choices. Removing the Automations Nuxt
+package from a host also requires removing its root Workflow binding.

package/client.ts

@@ -0,0 +1,24 @@
+import type { CommandRequest } from '@nuxtagentic/integrations/client'
+export interface AutomationLaunch {
+  runId: number
+  status: string
+  duplicate: boolean
+}
+/** Runtime commands complement, rather than replace, generated CloudConfig CRUD. */
+export function createAutomationCommands(request: CommandRequest) {
+  return {
+    run: (id: number, payload: unknown, options: { errorPath?: boolean; eventId?: string } = {}) =>
+      request<AutomationLaunch>(`/api/automations/${id}/run`, {
+        method: 'POST',
+        body: { payload, ...options },
+      }),
+    endpoint: (id: number) => request<{ url: string }>(`/api/automations/${id}/endpoint`),
+    integrationEndpoint: (provider: string) =>
+      request<{ url: string }>(`/api/automations/integration-hook/${encodeURIComponent(provider)}`),
+    emit: (event: string, payload: unknown, id: string) =>
+      request<{ runs: AutomationLaunch[] }>('/api/automations/events', {
+        method: 'POST',
+        body: { event, payload, id },
+      }),
+  }
+}

package/module.ts

@@ -0,0 +1,55 @@
+import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
+import { registerWorkspaceModule } from '@nuxtagentic/kit'
+
+export default defineNuxtModule({
+  meta: { name: '@nuxtagentic/automations' },
+  moduleDependencies: {
+    '@nuxtagentic/workspace': {},
+    '@nuxtagentic/agents': {},
+    '@nuxtagentic/integrations': {},
+  },
+  setup(_options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+    nuxt.options.runtimeConfig.automations = {
+      openaiApiKey: '',
+      anthropicApiKey: '',
+      googleAiApiKey: '',
+    }
+    registerWorkspaceModule(
+      {
+        id: 'automations',
+        runtime: resolver.resolve('./runtime'),
+        feature: {
+          from: resolver.resolve('./runtime/workspace.ts'),
+          name: 'automationsContribution',
+        },
+        metadata: resolver.resolve('./runtime/shared/agent.ts'),
+      },
+      nuxt,
+    )
+    nuxt.hook('pages:extend', (pages) => {
+      pages.push({
+        name: 'dashboard-automations',
+        path: '/dashboard/automations',
+        file: resolver.resolve('./runtime/pages/automations.vue'),
+      })
+    })
+    addServerHandler({
+      route: '/api/automation-hooks/:owner/:id/:token/:slug',
+      method: 'post',
+      handler: resolver.resolve('./runtime/server/handlers/automation-hook.post.ts'),
+    })
+    addServerHandler({
+      route: '/api/integration-hooks/:uid',
+      method: 'post',
+      handler: resolver.resolve('./runtime/server/handlers/integration-hook.post.ts'),
+    })
+    // Takes precedence over CloudConfig's own `/api/**` mount for this path, so
+    // verified vendor webhooks start automations with the request's context.
+    addServerHandler({
+      route: '/api/connect/hooks/:provider',
+      method: 'post',
+      handler: resolver.resolve('./runtime/server/handlers/connect-hook.post.ts'),
+    })
+  },
+})

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@nuxtagentic/automations",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "files": [
+    "module.ts",
+    "runtime",
+    "schema.ts",
+    "client.ts",
+    "README.md",
+    "server.ts",
+    "workflow.ts",
+    "LICENSE.md"
+  ],
+  "exports": {
+    ".": "./module.ts",
+    "./package.json": "./package.json",
+    "./schema": "./schema.ts",
+    "./client": "./client.ts",
+    "./server": "./server.ts",
+    "./workflow": "./workflow.ts",
+    "./runtime/*.vue": "./runtime/*.vue",
+    "./runtime/*.css": "./runtime/*.css",
+    "./runtime/*.json": "./runtime/*.json",
+    "./runtime/*.svg": "./runtime/*.svg",
+    "./runtime/*": "./runtime/*.ts"
+  },
+  "dependencies": {
+    "@cloudconfig/core": "0.2.0-beta.2",
+    "@nuxt/kit": "4.6.1",
+    "@nuxt/ui": "^4.11.1",
+    "@cloudflare/workers-types": "5.20261015.1",
+    "@vueuse/core": "^14.4.0",
+    "cron-parser": "^5.10.1",
+    "h3": "1.15.11",
+    "vue-router": "^5.4.0",
+    "@nuxtagentic/agents": "0.1.1",
+    "@nuxtagentic/workspace": "0.1.1",
+    "@nuxtagentic/kit": "0.1.1",
+    "@nuxtagentic/prompt": "0.1.1",
+    "@nuxtagentic/integrations": "0.1.1",
+    "@nuxtagentic/identity": "0.1.1",
+    "@nuxtagentic/google": "0.1.1"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.6.1",
+    "vue": "^3.5.43",
+    "nitropack": "^2.13.4"
+  },
+  "cloudconfig": {
+    "models": "automationsModels"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "description": "Durable agent workflows, triggers and approvals for Nuxt Agentic.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  }
 }