@flowdular/sdk 0.1.0

package/modules/automations/migrations/0002_automations_targets.up.sql

@@ -0,0 +1,37 @@
+ALTER TABLE automations_schedules
+  ADD COLUMN IF NOT EXISTS target_kind TEXT NOT NULL DEFAULT 'agent';
+ALTER TABLE automations_schedules
+  ADD COLUMN IF NOT EXISTS target_key TEXT;
+ALTER TABLE automations_schedules
+  ADD COLUMN IF NOT EXISTS configured_by_json TEXT;
+ALTER TABLE automations_schedules
+  ADD COLUMN IF NOT EXISTS permission_snapshot_json TEXT NOT NULL DEFAULT '[]';
+UPDATE automations_schedules
+SET target_key = agent_id
+WHERE target_key IS NULL;
+UPDATE automations_schedules
+SET configured_by_json = json_build_object(
+  'kind', 'user',
+  'id', created_by,
+  'label', created_by
+)::text
+WHERE configured_by_json IS NULL;
+
+ALTER TABLE automations_triggers
+  ADD COLUMN IF NOT EXISTS target_kind TEXT NOT NULL DEFAULT 'agent';
+ALTER TABLE automations_triggers
+  ADD COLUMN IF NOT EXISTS target_key TEXT;
+ALTER TABLE automations_triggers
+  ADD COLUMN IF NOT EXISTS configured_by_json TEXT;
+ALTER TABLE automations_triggers
+  ADD COLUMN IF NOT EXISTS permission_snapshot_json TEXT NOT NULL DEFAULT '[]';
+UPDATE automations_triggers
+SET target_key = agent_id
+WHERE target_key IS NULL;
+UPDATE automations_triggers
+SET configured_by_json = json_build_object(
+  'kind', 'user',
+  'id', created_by,
+  'label', created_by
+)::text
+WHERE configured_by_json IS NULL;

package/modules/automations/migrations/0003_automations_scheduler_role.down.sql

@@ -0,0 +1,3 @@
+REVOKE SELECT (tenant_id, id, next_run_at, enabled) ON automations_schedules FROM coreloom_background;
+DROP POLICY IF EXISTS automations_schedules_background_policy ON automations_schedules;
+DROP INDEX IF EXISTS automations_schedules_routing_idx;

package/modules/automations/migrations/0003_automations_scheduler_role.up.sql

@@ -0,0 +1,19 @@
+CREATE INDEX IF NOT EXISTS automations_schedules_routing_idx
+  ON automations_schedules (enabled, next_run_at, tenant_id, id);
+-- The scheduler must find due work across tenants. It is granted exactly the
+-- columns the poll reads and nothing else: labels, templates, the configuring
+-- actor and the permission snapshot stay invisible to it, and the schedule is
+-- read again under its own tenant before anything acts on it. PostgreSQL checks
+-- column privileges in WHERE too, so `enabled` is part of the grant.
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'coreloom_background') THEN
+    RAISE EXCEPTION 'The coreloom_background role must exist before this migration.';
+  END IF;
+END
+$$;
+CREATE POLICY automations_schedules_background_policy ON automations_schedules
+  FOR SELECT TO coreloom_background
+  USING (enabled = 1);
+REVOKE SELECT ON automations_schedules FROM coreloom_background;
+GRANT SELECT (tenant_id, id, next_run_at, enabled) ON automations_schedules TO coreloom_background;

package/modules/automations/migrations/0004_automations_trigger_routing_role.down.sql

@@ -0,0 +1,3 @@
+REVOKE SELECT (tenant_id, id) ON automations_triggers FROM coreloom_background;
+DROP POLICY IF EXISTS automations_triggers_background_policy ON automations_triggers;
+DROP INDEX IF EXISTS automations_triggers_routing_idx;

package/modules/automations/migrations/0004_automations_trigger_routing_role.up.sql

@@ -0,0 +1,18 @@
+CREATE INDEX IF NOT EXISTS automations_triggers_routing_idx
+  ON automations_triggers (id, tenant_id);
+-- A webhook arrives with a trigger id and no tenant, so the lookup must cross
+-- tenants. It is granted exactly the two columns that route it: the secret, the
+-- label, the target and the permission snapshot are read again under the tenant
+-- this returned, before anything is verified or fired.
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'coreloom_background') THEN
+    RAISE EXCEPTION 'The coreloom_background role must exist before this migration.';
+  END IF;
+END
+$$;
+CREATE POLICY automations_triggers_background_policy ON automations_triggers
+  FOR SELECT TO coreloom_background
+  USING (true);
+REVOKE SELECT ON automations_triggers FROM coreloom_background;
+GRANT SELECT (tenant_id, id) ON automations_triggers TO coreloom_background;

package/modules/automations/migrations/README.md

@@ -0,0 +1,3 @@
+# Migrations
+
+Migrations in this directory are append-only after release.

package/modules/automations/module.json

@@ -0,0 +1,31 @@
+{
+	"$schema": "../../packages/contracts/schemas/module.schema.json",
+	"schemaVersion": 1,
+	"id": "automations.core",
+	"package": "@flowdular/module-automations",
+	"version": "0.4.0",
+	"profile": "full",
+	"capabilities": ["api", "database", "client", "translations"],
+	"platform": {
+		"server": true,
+		"client": true
+	},
+	"dependencies": [
+		{
+			"id": "system.core",
+			"range": "0.5.0"
+		},
+		{
+			"id": "auth.core",
+			"range": "0.10.0"
+		},
+		{
+			"id": "agents.core",
+			"range": "0.9.1"
+		}
+	],
+	"tenancy": "required",
+	"locales": ["en", "pl"],
+	"stability": "experimental",
+	"platformApi": "0.1.0"
+}

package/modules/automations/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@flowdular/module-automations",
+	"version": "0.4.0",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client/index.ts",
+		"./server": "./src/server/index.ts",
+		"./platform": "./src/platform.ts",
+		"./module.json": "./module.json"
+	},
+	"scripts": {
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@flowdular/client": "workspace:*",
+		"@flowdular/contracts": "workspace:*",
+		"@flowdular/database": "workspace:*",
+		"@flowdular/kernel": "workspace:*",
+		"@flowdular/module-agents": "workspace:*",
+		"@flowdular/module-auth": "workspace:*",
+		"@flowdular/server": "workspace:*",
+		"@flowdular/ui": "workspace:*",
+		"octane": "0.1.51",
+		"segment-state": "0.2.0"
+	},
+	"devDependencies": {
+		"@flowdular/database-testing": "workspace:*",
+		"@tsrx/typescript-plugin": "0.3.120",
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.10"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
+		"directory": "modules/automations"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}

package/modules/automations/spec/module.yaml

@@ -0,0 +1,93 @@
+schemaVersion: 1
+id: automations.core
+specVersion: 0.4.0
+status: approved
+name: Automations Core
+description: Runs agents without a person present, on a schedule or from a signed webhook, as a module a workspace can leave uninstalled.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+dependencies:
+  - id: system.core
+    range: 0.5.0
+  - id: auth.core
+    range: 0.10.0
+  - id: agents.core
+    range: 0.9.1
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Automations never reads or writes another module's database; it reaches agents.core only through the agents.run-queue platform capability.
+  - A workspace with automations.core disabled keeps every agent capability, including manual runs, usage accounting, and budget caps.
+  - A schedule fires at most once per slot, and a slot missed while the platform was down is skipped, never replayed.
+  - A webhook request is accepted only with a fresh, valid signature; every refusal returns one identical response and the reason goes to the audit trail alone.
+  - The trigger secret is stored encrypted with the key held outside the database, and is returned in full only at creation and rotation.
+  - A schedule or trigger whose agent no longer exists disables itself and records why, because a cross-module reference cannot be a foreign key.
+  - Automation events are appended to a hash-chained audit trail that verifies independently of the agents trail.
+  - The scheduler poll interval is an automations.core platform setting with a bounded deployment default, so installing the module does not add an undeclared clock policy to agents.core.
+  - A schedule stores its raw input template; only the queued run snapshot receives a single-pass resolved value from scope-filtered variable sources.
+  - Every request-time read and write runs on a tenant-scoped PostgreSQL handle under forced row-level security. The scheduler poll and the webhook trigger lookup are the only cross-tenant reads, they run on a separate read-only role, and that role is granted only the columns that route the work to a tenant under a policy of the table itself.
+  - A due schedule found by the cross-tenant poll, and a trigger found by the cross-tenant webhook lookup, are read again under the tenant that row named before anything acts on them, and a slot whose next run time moved in between is skipped.
+permissions:
+  - id: automations.schedules.read
+    description: Read schedules in the active tenant.
+  - id: automations.schedules.manage
+    description: Create, update, delete, and run schedules in the active tenant.
+  - id: automations.triggers.read
+    description: Read webhook triggers in the active tenant.
+  - id: automations.triggers.manage
+    description: Create, update, rotate, and delete webhook triggers in the active tenant.
+dataOwnership:
+  - automations.core owns schedule definitions, webhook trigger definitions, their encrypted secrets, and its own audit trail.
+  - agents.core keeps runs, run history, token usage, cost accounting, and budget caps, so cost protection survives with automations uninstalled.
+  - Automations stores an agent identifier and never copies agent definitions, skills, or provider credentials.
+acceptanceScenarios:
+  - id: AUTO-SCHEDULE-FIRES
+    given: An enabled schedule on an existing agent is due.
+    when: The worker ticks twice inside the same slot.
+    then: Exactly one run is enqueued through the agents.run-queue capability and the next slot is computed from the fired slot.
+  - id: AUTO-SCHEDULE-MISSED
+    given: An enabled schedule was due several intervals ago because the platform was stopped.
+    when: The worker ticks after the platform starts.
+    then: One run is enqueued and the skipped slots are not replayed.
+  - id: AUTO-WEBHOOK-ACCEPT
+    given: A caller signs the body with the trigger secret and a fresh timestamp.
+    when: The request reaches the public fire endpoint.
+    then: A run is enqueued, the same signed request replayed lands on the run already queued, and no second run is created.
+  - id: AUTO-WEBHOOK-REFUSE
+    given: A request carries a wrong signature, an unknown trigger identifier, or a stale timestamp.
+    when: The request reaches the public fire endpoint.
+    then: All three receive one identical refusal that reveals nothing about which trigger exists, and the reason is recorded in the tenant audit trail only.
+  - id: AUTO-MISSING-AGENT
+    given: A schedule references an agent that was deleted in agents.core.
+    when: The schedule becomes due.
+    then: No run is enqueued, the schedule is disabled with a recorded reason, and the failure is visible on the schedule.
+  - id: AUTO-DENY
+    given: A principal is unauthenticated or lacks the required automations permission.
+    when: The principal reads or mutates a schedule or a trigger.
+    then: The server denies the operation before repository access.
+  - id: AUTO-OPTIONAL
+    given: A workspace has automations.core disabled.
+    when: A principal uses agents.core.
+    then: Definitions, runs, usage, and budget caps all work, and no automations navigation entry, permission, or route is present.
+  - id: AUTO-AUDIT-CHAIN
+    given: Schedules and triggers were created, updated, and deleted.
+    when: The automations audit trail is verified.
+    then: The chain verifies independently of the agents run trail.
+  - id: AUTO-SETTINGS
+    given: An administrator changes the scheduler poll interval within its declared bounds.
+    when: The automations runtime next starts.
+    then: Its scheduler uses the configured interval without changing the agents worker cadence.
+  - id: AUTO-SCHEDULE-VARIABLES
+    given: A schedule manager can read the variables offered by the schedule editor, including agent.name through the agents.run-queue public capability.
+    when: The manager saves a template containing known variables and the schedule queues a run.
+    then: Unknown or forbidden variables are rejected, the stored schedule keeps the raw template, and the run receives one-pass resolved input from the active tenant only.
+  - id: AUTO-POLL-NARROW
+    given: Two workspaces each own an enabled schedule that is due.
+    when: The scheduler polls for due work across tenants.
+    then: The poll returns only the workspace id, schedule id and next run time; the label, input template, configuring actor and permission snapshot are unreadable on that connection, and it cannot write.

package/modules/automations/src/acl/permissions.ts

@@ -0,0 +1,10 @@
+export const AUTOMATIONS_PERMISSIONS = {
+	read: 'automations.schedules.read',
+	manage: 'automations.schedules.manage',
+	triggersRead: 'automations.triggers.read',
+	triggersManage: 'automations.triggers.manage',
+} as const;
+
+export const permissions = Object.freeze(
+	Object.values(AUTOMATIONS_PERMISSIONS),
+);