@protobase/cli 0.67.11 → 0.68.0

package/dist/build/config-bundle.js

@@ -88,7 +88,7 @@ const buildConfigBundle = async ({ projectDir, outFile, bun, extensions = [], co
 		collectComponents(components),
 		extensionImports(projectDir, extensions),
 		servedImports(native),
-		entry(file, bundleEntryCode(projectDir, extensions, config.files?.images ? [config.files.images] : []))
+		entry(file, bundleEntryCode(projectDir, extensions, [...config.files?.images ? [config.files.images] : [], ...config.workflows?.plugins ?? []]))
 	];
 	await viteBundle({
 		root: projectDir,

package/dist/cli/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.67.11";
+var version = "0.68.0";
 //#endregion
 export { version };

package/dist/config/package-entry.js

@@ -0,0 +1,49 @@
+import { findPackageDirSync, packageName } from "../build/packages/package-dir.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+//#region src/config/package-entry.ts
+const conditions = [
+	"node",
+	"import",
+	"default"
+];
+const targetOf = (target) => {
+	if (target === void 0 || target === null) return void 0;
+	if (typeof target === "string") return target;
+	if (Array.isArray(target)) return target.map(targetOf).find((found) => found !== void 0);
+	const condition = Object.keys(target).find((key) => conditions.includes(key));
+	return condition === void 0 ? void 0 : targetOf(target[condition]);
+};
+const exportOf = (exported, subpath) => {
+	if (typeof exported === "string" || Array.isArray(exported) || exported === null) return subpath === "." ? targetOf(exported) : void 0;
+	if (!Object.keys(exported).every((key) => key.startsWith("."))) return subpath === "." ? targetOf(exported) : void 0;
+	return targetOf(exported[subpath]);
+};
+const mainOf = (dir, main = "index.js") => {
+	const found = [
+		main,
+		`${main}.js`,
+		path.join(main, "index.js")
+	].map((file) => path.join(dir, file)).find((file) => existsSync(file));
+	if (!found) throw new Error(`The package in ${dir} has no ${main}`);
+	return found;
+};
+/**
+* The file an `import` of `id`, such as `sharp` or `@acme/plugin/steps`, loads from `fromDir`, as Node's ES module
+* resolution finds it: through the package's `exports` with the `import` conditions, otherwise its `main` or
+* `index.js`.
+*/
+const packageEntry = (id, fromDir) => {
+	const name = packageName(id);
+	if (!name) throw new Error(`${id} is no package name`);
+	const dir = findPackageDirSync(name, fromDir);
+	if (!dir) throw new Error(`Cannot find the package ${name} from ${fromDir}; install it`);
+	const manifest = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
+	const subpath = `.${id.slice(name.length)}`;
+	if (manifest.exports === void 0) return subpath === "." ? mainOf(dir, manifest.main) : path.join(dir, subpath);
+	const target = exportOf(manifest.exports, subpath);
+	if (!target) throw new Error(`The package ${name} exports no ${subpath} to import`);
+	return path.join(dir, target);
+};
+//#endregion
+export { packageEntry };

package/dist/config/project-files.js

@@ -1,14 +1,15 @@
 import { conventionConfig } from "../project/convention.js";
 import { uiDirs } from "../project/convention-files.js";
 import { functionFiles } from "../project/functions-folder.js";
-import { createRequire } from "node:module";
+import { packageEntry } from "./package-entry.js";
 import { existsSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/config/project-files.ts
+const folderFiles = (projectDir, folder) => existsSync(path.join(projectDir, folder)) ? readdirSync(path.join(projectDir, folder)).filter((name) => name.endsWith(".ts") && !/\.(test|d)\.ts$/.test(name)).map((name) => `${folder}/${name}`).sort() : [];
 /** The files the conventions name besides resources and functions, which a bundle carries for its serve runtime. */
 const conventionModules = (projectDir) => {
-	const inFolder = (folder) => existsSync(path.join(projectDir, folder)) ? readdirSync(path.join(projectDir, folder)).filter((name) => name.endsWith(".ts") && !/\.(test|d)\.ts$/.test(name)).map((name) => `${folder}/${name}`) : [];
+	const inFolder = (folder) => folderFiles(projectDir, folder);
 	const files = [
 		"auth/hooks.ts",
 		"auth/authenticate.ts",
@@ -26,6 +27,7 @@ const conventionModules = (projectDir) => {
 		...inFolder("jobs"),
 		...inFolder("hooks"),
 		...inFolder("files"),
+		...inFolder("workflows/plugins"),
 		...files.filter((file) => existsSync(path.join(projectDir, file)))
 	].sort();
 };
@@ -42,9 +44,10 @@ const sourceFiles = (projectDir, importModules) => {
 		} },
 		functions: Object.fromEntries(functionFiles(projectDir).map(({ name, file }) => [name, one(file)])),
 		module: (file) => existsSync(path.join(projectDir, file)) ? one(path.join(projectDir, file)) : void 0,
+		folder: (folder) => folderFiles(projectDir, folder),
 		package: (name) => import(
 			/* @vite-ignore */
-			pathToFileURL(createRequire(path.join(projectDir, "package.json")).resolve(name)).href
+			pathToFileURL(packageEntry(name, projectDir)).href
 )
 	};
 };

package/dist/config/project-parts.js

@@ -192,13 +192,28 @@ const projectWebhooks = async (config) => {
 		...ownerRoles && { ownerRoles }
 	};
 };
-/** The workflows options, with the roles of workflows/saved-by-roles.ts when a config's folder has it. */
+const workflowPlugins = async (config, packages) => {
+	const project = config.sources.at(-1).files;
+	const fromPackages = await Promise.all(packages.map(async (name) => ({
+		plugin: (await project.package(name)).default,
+		source: name
+	})));
+	const fromFolders = await Promise.all(config.sources.flatMap(({ files, label }) => files.folder("workflows/plugins").map(async (file) => ({
+		plugin: (await files.module(file)()).default,
+		source: `${file} of ${label}`
+	}))));
+	return [...fromPackages, ...fromFolders];
+};
+/** The workflows options, with the roles of workflows/saved-by-roles.ts when a config's folder has it, and the app's plugins. */
 const projectWorkflows = async (config) => {
 	if (!config.workflows) return void 0;
+	const { plugins: packages = [], ...options } = config.workflows;
 	const savedByRoles = await lastDefault(config, "workflows/saved-by-roles.ts");
+	const plugins = await workflowPlugins(config, packages);
 	return {
-		...config.workflows,
-		...savedByRoles && { savedByRoles }
+		...options,
+		...savedByRoles && { savedByRoles },
+		...plugins.length > 0 && { plugins }
 	};
 };
 /**

package/dist/host-modules.json

@@ -6,6 +6,7 @@
   "@protobase/query",
   "@protobase/server",
   "@protobase/server/pdf",
+  "@protobase/workflows/plugin",
   "@protobase/server/email",
   "kysely",
   "kysely/helpers/postgres",

package/dist/serve/host-module-ids.js

@@ -8,6 +8,7 @@ const hostModuleIds = [
 	"@protobase/query",
 	"@protobase/server",
 	"@protobase/server/pdf",
+	"@protobase/workflows/plugin",
 	...lazyHostModuleIds,
 	"kysely",
 	"kysely/helpers/postgres",

package/dist/serve/host-modules.js

@@ -21,6 +21,7 @@ import * as reactJsxRuntime from "react/jsx-runtime";
 import * as zod from "zod";
 import * as protobaseConfig from "@protobase/config";
 import * as pdf from "@protobase/server/pdf";
+import * as workflowPlugin from "@protobase/workflows/plugin";
 //#region src/serve/host-modules.ts
 const hostModules = {
 	"@protobase/config": protobaseConfig,
@@ -30,6 +31,7 @@ const hostModules = {
 	"@protobase/query": query,
 	"@protobase/server": server,
 	"@protobase/server/pdf": pdf,
+	"@protobase/workflows/plugin": workflowPlugin,
 	kysely,
 	"kysely/helpers/postgres": kyselyPostgres,
 	pg: pg$1,

package/dist/serve/load-bundle.js

@@ -15,6 +15,7 @@ const projectFiles = ({ resources, functions, modules }, packages) => ({
 	...resources && { resources },
 	functions,
 	module: (file) => modules[file],
+	folder: (folder) => Object.keys(modules).filter((file) => file.startsWith(`${folder}/`) && !file.slice(folder.length + 1).includes("/")).sort(),
 	package: async (name) => {
 		const load = packages[name];
 		if (!load) throw new Error(`The bundle carries no ${name}; build it again`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.67.11",
+  "version": "0.68.0",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,12 +43,13 @@
   "dependencies": {
     "@better-auth/core": "^1.7.12",
     "@hono/node-server": "^2.1.3",
-    "@protobase/config": "0.67.11",
-    "@protobase/layout": "0.67.11",
-    "@protobase/query": "0.67.11",
-    "@protobase/schema": "0.67.11",
-    "@protobase/server": "0.67.11",
-    "@protobase/ui": "0.67.11",
+    "@protobase/config": "0.68.0",
+    "@protobase/layout": "0.68.0",
+    "@protobase/query": "0.68.0",
+    "@protobase/schema": "0.68.0",
+    "@protobase/server": "0.68.0",
+    "@protobase/ui": "0.68.0",
+    "@protobase/workflows": "0.68.0",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/vite-plugin": "^11.10.0",

package/skills/protobase/SKILL.md

@@ -89,6 +89,7 @@ Reference:
 - When letting people without an account create records → read [Public forms](references/reference/forms.md)
 - When running background jobs → read [Jobs](references/reference/jobs.md)
 - When writing or running workflows, their steps and their runs → read [Workflows](references/reference/workflows.md)
+- When adding trigger or step types to workflows → read [Workflow plugins](references/reference/workflow-plugins.md)
 - When sending email → read [Email](references/reference/email.md)
 - When making a PDF file, such as an invoice, a quote or a report → read [PDF documents](references/reference/pdf.md)
 - When registering users' devices for push notifications → read [Notifications](references/reference/notifications.md)

package/skills/protobase/references/features/record-pages.md

@@ -11,6 +11,7 @@ The page of one record, with its sections, related records, galleries, charts an
 - [Unsaved edits](../reference/ui-config.md#editing-a-record): Unsaved changes to a record stay in the browser and can be resumed, and leaving a form, a dialog or a comment with changes asks first.
 - [Record forms](../reference/ui-config.md#editing-a-record): Relations are picked from a list that narrows as you type, numbers are read as the browser's language writes them, and a refused save says under each field what is wrong.
 - [Titles per reader](../reference/ui-config.md#titles-per-reader): A record without a name of its own, such as a direct message, is titled for each reader from its fields, such as after the other members, in the sidebar, breadcrumbs, heading, browser tab, relation links, list columns, relation pickers, filters and search.
+- [JSON fields on forms](../reference/plugins.md#json) (beta): A JSON field, such as a workflow run's input, is edited on forms as JSON text and shown written out on several lines.
 - [Member fields](../reference/plugins.md#members): A field that holds a list of people, such as a private channel's members, picks the organization's members by name on forms and shows them by avatar and name.
 - [Save feedback](../reference/ui-config.md#the-record-page): A view shows saving on the Save button instead of in a toast.
 - [Save conflicts](../reference/ui-config.md#editing-a-record): When someone else changed a record while you edited it, Save shows their value beside yours for each field you both changed, and you keep yours or take theirs.

package/skills/protobase/references/features/workflows.md

@@ -7,12 +7,20 @@ Graphs of steps the server runs along their edges, written in a language a model
 - [Workflows](../reference/workflows.md#turning-them-on) (beta): Workflows kept in the app's database, each changed definition checked and kept as a version, run on the app's own jobs.
 - [Workflow language](../reference/workflows.md#the-document) (beta): The States Language with JSONata expressions, every value read by name, so a model writes and edits it as a small, local change.
 - [Checked on save](../reference/workflows.md#reading-values-by-name) (beta): A definition that does not fit the language, has an edge to no step, reads a value nothing gives or leaves out an argument its step type needs is refused, naming the step and the field.
-- [Workflow editor](../reference/workflows.md#the-editor) (beta): The admin app draws a workflow as a graph that lays itself out, to add, connect and remove steps and fill in each step's form, with every problem the save would refuse shown on its step as it is edited.
+- [Workflow editor](../reference/workflows.md#the-editor) (beta): The admin app draws a workflow as a graph that lays itself out, to add, connect and remove steps of every trigger and step type of the app, its plugins' included, each with a form for its input, with every problem the save would refuse shown on its step as it is edited.
 - [Branches, steps per item and retries](../reference/workflows.md#states) (beta): Choices, a step per item with their results merged, waits, and per-step retries, timeouts and error paths.
 - [HTTP request step](../reference/workflows.md#apphttp) (beta): Calls a URL built at run time through the outgoing-address guard, only at public addresses unless the config allows private ones, reading at most 10 MiB of the answer as JSON, text or a file.
 - [Records steps](../reference/workflows.md#apprecords) (beta): Create, update, get and list records as the workflow's last editor, with the roles they hold now.
 - [Mail step](../reference/workflows.md#appmailsend) (beta): Sends mail, with files the run downloaded attached, from the app's own sender.
-- [Runs and step records](../reference/workflows.md#runs-and-their-steps) (beta): Each run started by hand through the API or from the app's code, with every step's input, output, logs, timing, tries and error recorded, secrets blanked out.
+- [Runs and step records](../reference/workflows.md#runs-and-their-steps) (beta): Each run started by hand through the API, from the app's code or by a trigger, with every step's input, output, logs, timing, tries and error recorded, secrets blanked out.
+- [Run debugger](../reference/workflows.md#following-and-debugging-a-run) (beta): Each workflow lists its runs with their status, who started them, when and for how long; a run's page marks every step's status on the workflow's graph, live while it runs, with each step's input, output, logs, timing, tries and error, secrets blanked out.
+- [Re-run from the failed step](../reference/workflows.md#re-running-a-failed-run) (beta): Once the workflow is fixed, a failed run runs again from the step that failed, keeping what the steps before it gave; a test run starts the workflow with a sample input from its page.
 - [Runs that survive restarts](../reference/workflows.md#how-a-run-is-run) (beta): A run takes up where it stood after a restart or a crashed worker, never running a saved step again, and every limit fails closed.
 - [Who may run workflows](../reference/workflows.md#who-may-do-what) (beta): Making, changing and running workflows and reading their runs are each granted by name, within the tenant.
-- [Workflows over MCP](../reference/mcp.md#workflows) (beta): AI clients find, write, validate, change by a small edit and test-run workflows as the signed-in person, and read each step of a run to fix the one that failed.
+- [Workflows over MCP](../reference/mcp.md#workflows) (beta): AI clients find, write, validate, change by a small edit and test-run workflows as the signed-in person, and read each step of a run to fix the one that failed and re-run it from there.
+- [Record triggers](../reference/workflows.md#apprecord) (beta): A workflow starts once for each record that becomes ready, at once or when a time in it comes, read as the user who saved the enabled version.
+- [Triggers turned on while the app runs](../reference/workflows.md#turning-a-trigger-on) (beta): Turning a workflow on or changing it registers its trigger on every server process, and turning it off stops it, with no restart.
+- [Workflow plugins](../reference/workflow-plugins.md) (beta): A file of the app or a package adds trigger and step types through the same public interface the built-in types use.
+- [Guarded requests for plugins](../reference/workflow-plugins.md#sending-requests) (beta): A plugin's requests reach only public addresses, follow no redirect and read at most 10 MiB.
+- [Webhook trigger](../reference/workflow-plugins.md#polling-and-webhook-coming-soon) (coming soon): A workflow starts from a signed call to a URL of its own, limited in size and rate.
+- [Polling triggers](../reference/workflow-plugins.md#polling-and-webhook-coming-soon) (coming soon): A workflow starts once for each new item a plugin finds on a schedule.

package/skills/protobase/references/reference/config/jobs-and-events.md

@@ -211,7 +211,7 @@ export default defineConfig(({ command }) => ({ webhooks: { allowPrivateAddresse
 
 ## workflows
 
-- **Type:** `{ schema?: string; secrets?: string[]; allowPrivateAddresses?: boolean }`
+- **Type:** `{ schema?: string; secrets?: string[]; allowPrivateAddresses?: boolean; plugins?: string[] }`
 - **Default:** off; `{}` turns them on
 
 Workflows that people and models make in the app, kept with their versions, runs and steps in a schema of the app's database that `protobase migration` writes, and run by the `workflows.segment` job. Records steps act as each workflow's last editor, with the roles they hold now, read from the app's sign-in; a project that signs people in otherwise exports its own, `async ({ id, tenant }) => [...]`, as the default of `workflows/saved-by-roles.ts`. See [Workflows](../workflows.md).
@@ -247,12 +247,23 @@ export default defineConfig({ workflows: { secrets: ['TICKETS_TOKEN'] } })
 - **Type:** `boolean`
 - **Default:** `false`
 
-Lets the `app:http` step reach private, loopback and link-local addresses, for development and tests. Off, a URL whose host resolves to one fails the step, which connects only to the address it checked, so a workflow cannot reach the app's own network.
+Lets the `app:http` step, and every plugin's `fetch`, reach private, loopback and link-local addresses, for development and tests. Off, a URL whose host resolves to one fails the request, which connects only to the address it checked, so a workflow cannot reach the app's own network.
 
 ```ts
 export default defineConfig(({ command }) => ({ workflows: { allowPrivateAddresses: command === 'dev' } }))
 ```
 
+## workflows.plugins
+
+- **Type:** `string[]`
+- **Default:** none
+
+Packages of [workflow plugins](../workflow-plugins.md) the app runs, by package name, beside the built-in types and the app's own plugins in `workflows/plugins/<name>.ts`. Two plugins of one name stop startup, naming both.
+
+```ts
+export default defineConfig({ workflows: { plugins: ['@acme/workflow-plugin'] } })
+```
+
 ## notifications
 
 - **Type:** `{ ui?: boolean; schema?: string; devices?: { table?: string; columns?: Record<string, string> }; history?: { table?: string; columns?: Record<string, string> } }`

package/skills/protobase/references/reference/config.md

@@ -141,6 +141,7 @@ The other files belong to an option, and are described with it:
 | `jobs/<name>.ts` | [`jobs`](config/jobs-and-events.md#jobs) |
 | `webhooks/owner-roles.ts` | [`webhooks`](config/jobs-and-events.md#webhooks) |
 | `workflows/saved-by-roles.ts` | [`workflows`](config/jobs-and-events.md#workflows) |
+| `workflows/plugins/<name>.ts` | [`workflows.plugins`](config/jobs-and-events.md#workflowsplugins) |
 | `notifications/store.ts`, `notifications/history-store.ts`, `notifications/senders.ts` | [`notifications`](config/jobs-and-events.md#notifications) |
 | `files/<name>.ts` | [`files.providers`](config/files.md#filesproviders) |
 
@@ -163,6 +164,7 @@ export default defineUi({ extends: [tasksUi] })
 | assistant tools of `assistant/tools.ts` | the extensions' first, in order, then the app's | an error naming the tool and both folders |
 | MCP tools of `mcp/tools.ts` | the extensions' first, in order, then the app's | an error naming the tool and both folders |
 | `jobs`, functions, file providers (`files.providers`) | all kept, by name | an error naming the name and both folders |
+| workflow plugins of `workflows/plugins/` | all kept | an error naming the plugin and both sources |
 | `files.trustedHosts` | all kept | |
 | the other keys of `files` | each the app's own; otherwise the last config that sets it | |
 | `writeHooks` | all run, in the same order | |

package/skills/protobase/references/reference/mcp.md

@@ -92,14 +92,14 @@ In an app with [workflows](workflows.md), the endpoint also offers tools to find
 
 | Tool | What it does |
 | --- | --- |
-| `list_workflow_types` | The step types a Task names as its `Resource`, each with its arguments (required or not, and what each takes), its result and the errors it fails with; and the triggers, how the definition holds each and the input a run gets from it. |
+| `list_workflow_types` | The step types a Task names as its `Resource` and the triggers a definition holds, built-in and [plugin](workflow-plugins.md) ones alike, each by id with its label, description, input as JSON Schema and, when the type declares one, its output, the errors a step fails with, and whether the app can run it. |
 | `list_workflows` | A page of the workflows the person may read, newest change first, without their definitions: `filter` on `name`, `page_size` (20 by default, at most 100) and `page_token`. |
 | `get_workflow` | One workflow with its whole definition and its ETag. |
-| `validate_workflow` | Checks a `definition`, or a workflow's `id` with an `edit` of its saved definition, as a save checks it, and saves nothing: `{ valid: true }`, or `{ valid: false, problems }`. |
+| `validate_workflow` | Checks a `definition`, or a workflow's `id` with an `edit` of its saved definition, as a save checks it, and saves nothing: `{ valid: true }`, or `{ valid: false, problems }`. A record trigger is checked against the resources and fields the person may read, so a resource they cannot read is not a resource of the app. |
 | `get_workflow_run` | A run's status, input, output, error and cause, with its steps in the order they ran, each with its state, scope, try, status, input, output, assigned variables, logs, error and cause; `state` reads one state's steps, a page of 20 by default. |
 | `create_workflow` | Creates a workflow from its `name`, `description` and `definition`, and returns its `id`, `version` and ETag. |
 | `update_workflow` | Changes a workflow's definition by an `edit` or whole, as `definition`, and its `name` or `description`, and returns its `id`, new `version` and ETag. With the `etag` that `get_workflow` gave, it fails when someone changed the workflow since; an edit without one is saved against the version it was applied to. |
-| `run_workflow` | Starts a run of a workflow's current version with an `input`, and returns its `run_id` and `status`. |
+| `run_workflow` | Starts a run of a workflow's current version with an `input`, and returns its `run_id` and `status`. With `rerun_of`, a failed run's id, it [re-runs](workflows.md#re-running-a-failed-run) that run from its failed step instead, on its input. |
 
 An `edit` is a [JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7396) of the saved definition: only what changes, at its place in the document. An object merges into the object there, `null` removes a member, and any other value, a list included, replaces it. Changing one argument of one state:
 
@@ -107,7 +107,7 @@ An `edit` is a [JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7396) of the
 { "id": "...", "edit": { "stateMachine": { "States": { "Notify": { "Arguments": { "url": "https://hooks.example.com/v2" } } } } } }
 ```
 
-A definition the save check refuses comes back as `{ "error": "invalid-workflow", "message": ..., "problems": [...] }`, each problem `{ state, field, message }` naming the state, the field and what was expected, as `validate_workflow` gives them; nothing is saved. A run goes on in the background on the app's jobs, so `run_workflow` returns while it is queued: the client reads it with `get_workflow_run` until it has `succeeded` or `failed`, fixes the step that failed and runs it again.
+A definition the save check refuses comes back as `{ "error": "invalid-workflow", "message": ..., "problems": [...] }`, each problem `{ state, field, message }` naming the state, the field and what was expected, as `validate_workflow` gives them; nothing is saved. A run goes on in the background on the app's jobs, so `run_workflow` returns while it is queued: the client reads it with `get_workflow_run` until it has `succeeded` or `failed`, fixes the step that failed and re-runs the run from that step.
 
 `create_workflow`, `update_workflow` and `run_workflow` come with [writes](#writes), and the person approves each first, as any write, unless they hold one of the [roles without approval](#writes-without-approval); with writes limited to some resources, they save on `workflows` and run on `workflow_runs` only when the list names them. A run does what its steps do, such as requests, mail and record writes, as the workflow's last editor.
 
@@ -280,8 +280,9 @@ The endpoint serves each request on its own, without an MCP session: a `GET` or
 
 - `mcpHandler({ authenticate, resource, scope, server })`: the endpoint as a fetch handler. It checks the host, admits a valid token (`mcpGate`) and serves the request with the server that `server(session, request)` builds for its caller; `request` is the HTTP request, such as for the language the person reads.
 - `mcpServer({ info, instructions, tools, context, report, rolesWithoutApproval, approvals })`: an MCP server named by `info`, its `name`, `version` and `icons`, such as `mcpIcons(origin, icons)`, the app's icons on `origin`, and offering [assistant tools](assistant.md#the-apps-own-tools), each with its JSON Schema, its `annotations`, MCP's tool hints, and its `title` and `_meta`, and each refusing as [the app's own tools](#the-apps-own-tools) do. `context` is the tools' context without `approve`, with the `locale` its approvals are asked in (English when absent): each call gets its own, which asks the client's user, or approves at once when the session's user holds one of `rolesWithoutApproval`. It is a `ToolContext`, with the app's `records`, `resources()` and `show`, unless every tool is declared with a smaller one, such as `defineTool<BaseToolContext>(...)`, whose context is only `session`, `locale` and `approve`: a host without app records then passes `{ session }`. `report` gets what a tool throws other than a refusal. `approvals` is `mcpApprovals()`, built once and passed to every server the endpoint builds: it keeps the approvals asked for until they are answered or expire. `instructions` is what it tells clients when they connect, by default `mcpInstructions`, the advice on reading records above.
-- `mcpTools({ db, sql, writes, commented, workflows, own })`: the endpoint's tools for a session; `writes` is `true`, `false` or `{ resources, rolesWithoutApproval }`, `commented` names the resources with comments, `workflows: true` offers the [workflow tools](#workflows), and `own` are [the app's own tools](#the-apps-own-tools), offered after the rest.
-- `workflowReadTools()` and `workflowWriteTools({ resources })`: the workflow tools alone, and `workflowInstructions`, what the endpoint tells clients about the language, to append to `mcpInstructions`.
+- `mcpTools({ db, sql, writes, commented, workflows, own })`: the endpoint's tools for a session; `writes` is `true`, `false` or `{ resources, rolesWithoutApproval }`, `commented` names the resources with comments, `workflows` offers the [workflow tools](#workflows) with the app's types, and `own` are [the app's own tools](#the-apps-own-tools), offered after the rest.
+- `workflowTypes(plugins, models)`: the app's workflow types, a `WorkflowCatalog`, which `workflows` and `workflowReadTools` take. `plugins` are the app's own [workflow plugins](workflow-plugins.md), each `{ plugin, source }`, beside the built-in ones, and `models(name)` gives the model of the app's resource of that name, which a record trigger is checked against. An app with `workflows` needs none of this: its endpoint offers the tools with the app's types; these are for an MCP server of your own.
+- `workflowReadTools(catalog)` and `workflowWriteTools({ resources })`: the workflow tools alone, and `workflowInstructions`, what the endpoint tells clients about the language, to append to `mcpInstructions`.
 - `readRecordTools()`, or `listResourcesTool()`, `describeResourceTool()`, `listRecordsTool()` and `getRecordTool()`: the read tools alone; `readOnlyQueryTool(db)` is `run_read_only_query`, and `readWriteQueryTool(db)` proposes one write statement that the user approves before it runs.
 - `commentTools({ commented }, writes)`, or `listCommentsTool({ commented })` and `addCommentTool({ commented, resources })`: the comment tools on the resources named in `commented`, which call the context's `comments`, and `add_comment` only when `writes` is not `false`.
 - `writeRecordTools({ resources })`, or `createRecordTool(...)`, `updateRecordTool(...)` and `deleteRecordTool(...)`: the single write tools alone, on the listed resources or, without `resources`, on any; `batchWriteTool({ resources })` is `batch_write` alone.

package/skills/protobase/references/reference/plugins.md

@@ -149,6 +149,10 @@ Each part gets:
 
 [Adding a field type](../guides/field-type.md) builds one step by step.
 
+### JSON
+
+`json` is a field type Protobase brings for any JSON field a form should edit, such as a workflow run's `input`: `r.input.widget('json')`. The form edits the value as JSON text, the record page shows it written out on several lines, and a list's table on one. Text that does not parse yet says so under the box and leaves the value as it last parsed; an emptied box is null. It takes the form's whole width. A plugin that registers a field type named `json` replaces it.
+
 ### Members
 
 `members` is a field type Protobase brings, for a JSON field that holds an array of user ids, such as who may read a private channel. No plugin registers it; a view picks it as it picks any other:
@@ -167,6 +171,8 @@ The create form and the record's form pick the members of the organization the s
 
 `workflow` is the field type the `workflows` resource draws its `definition` with: the [workflow editor](workflows.md#the-editor). Another JSON field holding a workflow's definition picks it as `r.definition.widget('workflow')`. It takes the form's whole width, and a list's table shows how many steps the workflow has. A plugin that registers a field type named `workflow` replaces it.
 
+`workflow_run` is the field type the `workflow_runs` resource draws its own `id` with: the run's [trace](workflows.md#following-and-debugging-a-run) on its workflow's graph, with the chosen step's records under it. Another uuid field holding a run's id picks it as `r.run_id.widget('workflow_run')`. It takes the whole width, and a list's table shows the id. A plugin that registers a field type named `workflow_run` replaces it.
+
 ## Building
 
 ```sh

package/skills/protobase/references/reference/versioning.md

@@ -53,7 +53,7 @@ Every commit message follows [Conventional Commits](https://www.conventionalcomm
 
 When `main` moved on while the checks ran, the run of the newer push releases both. `bun run release --dry-run` prints the next version and its notes without tagging anything.
 
-A push made with GitHub Actions' own token, such as a pull request the AI review merged, [starts no workflow](https://docs.github.com/en/actions/concepts/security/github_token), but a run by hand always starts one. Running the workflow by hand from `main` without a tag (`gh workflow run release.yml`) releases `main`'s head as a push does, with the same checks, which then run in full, commitlint over the commits since the last `v<version>` tag, and the same release. A release started while another runs waits for it.
+A push made with GitHub Actions' own token, such as a pull request the AI review merged, [starts no workflow](https://docs.github.com/en/actions/concepts/security/github_token), but a run by hand always starts one. Running the workflow by hand from `main` without a tag (`gh workflow run release.yml`) releases `main`'s head as a push does, with the same checks, which then run in full, commitlint over the commits since the head the previous release run of `main` linted, as a push lints those since the previous push (the commits since the last `v<version>` tag when no recent run linted), and the same release. A malformed message that reached `main` so fails one release, not every later one. A release started while another runs waits for it.
 
 Running the workflow by hand with a tag (`gh workflow run release.yml -f tag=v0.1.0`) only packs and publishes: the packages at that tag and its version, skipping every version npm already has, and the images, which repeats a missed or half-done publish. A publish that npm fails because it could not read the identity token, or because Sigstore's transparency log already holds its provenance (a 409 after npm's own retry), is tried again up to 3 times, and the 409 counts as published when npm has the version; any other failure fails the run. `node scripts/publish.mjs --dry-run` packs the packages and shows what `npm publish` would send, and `node scripts/publish.mjs --pack`, which CI runs, packs every package without asking npm or publishing. Each package on npm trusts `release.yml` of `PrototeamHQ/protobase` as its publisher; a new package has to be published once by hand before that can be set up. The workflow pushes the images with its own token; a new image on GitHub's registry starts out private and is made public once in its package settings.
 

package/skills/protobase/references/reference/workflow-plugins.md

@@ -0,0 +1,119 @@
+<!-- Generated by scripts/protobase-skill.ts from docs/website/src/content/docs/reference/workflow-plugins.md: run `bun run docs:skill`, do not edit. -->
+
+# Workflow plugins
+
+Add trigger and step types to workflows from a file of the app or a package, through the same public interface the built-in types use.
+
+:::caution[Beta]
+Plugins add step types and record triggers. Polling and webhook triggers, and connections that sign in to other services, are declared by the interface but not run yet.
+:::
+
+A **workflow plugin** adds trigger and step types to an app's [workflows](workflows.md). Its types are named `<plugin>:<key>`, such as `acme:create_invoice`: a Task names a step type as its `Resource`, and a definition's `trigger` holds a trigger type with its input. The built-in types, `app:http`, `app:records.*`, `app:mail.send` and `app:record`, are a plugin like any other, written on this interface alone, so a plugin's types run, are checked and are listed exactly as they are.
+
+## Writing a plugin
+
+```ts
+// workflows/plugins/acme.ts
+import { definePlugin, StepError } from '@protobase/workflows/plugin'
+
+export default definePlugin({
+  name: 'acme',
+  label: 'Acme',
+  steps: {
+    create_invoice: {
+      label: 'Create an invoice',
+      description: 'Creates an invoice at Acme for a customer.',
+      errorPrefix: 'Acme',
+      errors: { Refused: 'Acme refused the invoice; its answer is in the cause' },
+      input: {
+        type: 'object',
+        required: ['customer', 'amount'],
+        properties: { customer: { type: 'string' }, amount: { type: 'number', minimum: 0 } },
+      },
+      output: { type: 'object', properties: { id: { type: 'string' } } },
+      run: async ({ input, fetch, signal, redact, idempotencyKey }) => {
+        const answer = await fetch('https://api.acme.example/invoices', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'idempotency-key': idempotencyKey },
+          body: JSON.stringify(input),
+          signal,
+        })
+        if (!answer.ok) throw new StepError('Acme.Refused', `${answer.status}: ${redact(await answer.text()).slice(0, 200)}`)
+        return { id: ((await answer.json()) as { id: string }).id }
+      },
+    },
+  },
+})
+```
+
+`definePlugin` checks the plugin's names: its `name` is lowercase letters, digits and `_`, each type's key is lowercase words joined by `_` or `.`, and a type that names a connection must find it among the plugin's `connections`.
+
+### Installing it
+
+- **The app's own:** the default export of `workflows/plugins/<name>.ts`, found by its path as jobs are. An [extension](config.md#extensions) adds its own from its folder.
+- **From a package:** listed by name in [`workflows.plugins`](config/jobs-and-events.md#workflowsplugins), its default export the plugin. The package is a dependency of the app.
+
+Two plugins of one name stop startup, naming both. A plugin is server code that runs with the app's rights, like the app's own code: load only plugins you trust. The interface's version is `pluginApi`, `1`; releases add optional keys to it and never break it.
+
+## Step types
+
+| Key | |
+| --- | --- |
+| `label`, `description` | What the type list shows, to a person and to a model. |
+| `input` | The JSON Schema of the Task's `Arguments`, checked before `run`: arguments that do not fit fail the step as `<errorPrefix>.InvalidArguments`, naming the field. |
+| `output` | The JSON Schema of what `run` returns, for the type list. |
+| `errorPrefix`, `errors` | The prefix of its error names, `Step` by default, and the errors it fails with by name, each with what it means. |
+| `connection` | The connection it signs in with, by the name the plugin declares it under. |
+| `run(context)` | Returns the step's result. It throws a `StepError` to fail with an error name of its own; any other error is `States.TaskFailed`. |
+
+What `run` gets, and nothing more:
+
+| | |
+| --- | --- |
+| `input` | The Task's evaluated `Arguments`, checked. |
+| `fetch(url, init)` | The only way a plugin should send a request: see [Sending requests](#sending-requests). |
+| `records` | `create`, `createMany`, `update`, `get` and `list` of the app's records, through the API as the user who saved the version the run runs, with the roles they hold now: their access rules, tenant, validation and write hooks apply. A refusal fails the step with `Records.Refused`. |
+| `files` | `keep(bytes, name, type)` stores a file of the run and returns its file value; `read(value, field)` reads one the run kept. No other file of the app is reachable. |
+| `mail` | `send(message)` from the app's own sender; `undefined` when the app sends no mail. |
+| `connection` | `accessToken()` of the connection the step declares, or `undefined`. |
+| `runId`, `idempotencyKey` | The run, and a key that every retry of this visit of the step shares, while a later visit of the same state, such as in a loop, gets a new one: send it where the receiver deduplicates. |
+| `signal` | Aborted at the step's timeout, or when the worker stops; pass it on to `fetch`. |
+| `log(message)`, `redact(text)` | A line in the step's logs, and the text with the app's secrets blanked out, both as the runner records them. |
+
+### Sending requests
+
+`fetch` resolves the URL's host once, refuses it unless every address is public, and connects to the very address it checked, so a URL built from a run's data cannot reach the app's own network or a cloud metadata address. It follows no redirect: a 3xx comes back as it is, and a plugin that follows one calls `fetch` again with the new URL, whose host is checked in turn. It reads at most `maxBytes` of the answer's body as it comes, 10 MiB by default and at most, and never decodes a `Content-Encoding`, so a large or endless answer fails with `ResponseTooLargeError` instead of filling memory; a refused address fails with `AddressRefusedError`. [`workflows.allowPrivateAddresses`](config/jobs-and-events.md#workflowsallowprivateaddresses) lets it reach private addresses, for development and tests.
+
+A plugin sends through `context.fetch`, never through the global `fetch`, Node's `http`, `https`, `net` or `tls`, or an HTTP client of its own: those are not guarded, so a workflow's data could make them reach the app's own network. The built-in plugins are held to this by the repository's boundary check, which fails on any of them.
+
+## Trigger types
+
+A trigger type has a `label`, a `description`, an `input` schema that a save checks the trigger's input against, an optional `check(input)` for what a schema cannot say, and a `kind`.
+
+### Ready
+
+```ts
+triggers: {
+  overdue: {
+    kind: 'ready',
+    label: 'Overdue invoice',
+    description: 'Starts a run for each invoice three days past its due date.',
+    input: { type: 'object', properties: {} },
+    ready: () => ({ resource: 'invoices', when: "status = 'sent' AND due_at <= now() - 3d", key: ['due_at'] }),
+  },
+},
+```
+
+`ready(input)` returns the resource, the readiness filter `when` and the `key` fields, and the engine runs it as it runs [`app:record`](workflows.md#apprecord): one run per record that becomes ready, at the time its time terms say, read as the user who saved the enabled version.
+
+### Polling and webhook (coming soon)
+
+The interface declares `kind: 'polling'`, with `every`, `limit`, `start` and `poll`, and `kind: 'webhook'`, with `receive` and the optional `subscribe`, `unsubscribe` and `renew`. <gap>A plugin's polling or webhook trigger cannot start runs because the polling and webhook triggers are not implemented; the type list marks them unavailable.</gap>
+
+## Connections (coming soon)
+
+`connections` declares the sign-ins a plugin's types use: one of the app's sign-in providers by name (`signIn`), or an OAuth provider of its own (`oauth`), with the `scopes` it asks for. A step or trigger names one as its `connection`, and gets only that one, through the workflow's own binding: the context takes no connection id, so a plugin cannot reach another workflow's sign-in. <gap>A type that declares a connection cannot run because connections are not implemented; the type list marks it unavailable, and a save that uses it is refused.</gap>
+
+## The type list
+
+[`list_workflow_types`](mcp.md#workflows) over MCP lists every step and trigger type the app has, built-in and plugin ones alike, as their plugins declare them: id, label, description, input and output schemas, errors and connection, with `available: false` and a reason for a type the app cannot run. A save, and `validate_workflow`, check a definition against the same list.

package/skills/protobase/references/reference/workflows.md

@@ -5,7 +5,7 @@
 Workflows written as state machines in the States Language with JSONata, checked on every save, run step by step on the app's jobs, with every step recorded.
 
 :::caution[Beta]
-Workflows run when they are started through the API, over MCP or from the app's code. Triggers and sign-in connections to other services are not built yet.
+Workflows run when they are started through the API, over MCP, from the app's code or by a test run in the admin app, and from record triggers. Webhook and polling triggers and sign-in connections to other services are not built yet.
 :::
 
 A **workflow** is a graph of steps that the server runs one after another along its edges: fetch something, decide, run a step per item, merge the results, write records, send mail. It is written in the **States Language**, the JSON language of state machines, with **JSONata** as its expression language, in a profile of it that reads every value by name. A language model writes and changes it as easily as a person, and the same document is what the server checks and runs. Each run records every step it takes, with what the step read, gave and logged.
@@ -18,20 +18,22 @@ import { defineConfig } from '@protobase/config'
 export default defineConfig({ workflows: { secrets: ['TICKETS_TOKEN'] } })
 ```
 
-It adds four resources, over a `workflows` schema that [`protobase migration`](cli.md#migration) writes (`NNN_workflows.sql`), and the `workflows.segment` [job](jobs.md) that runs them:
+It adds five resources, over a `workflows` schema that [`protobase migration`](cli.md#migration) writes (`NNN_workflows.sql`), and the `workflows.segment` [job](jobs.md) that runs them:
 
 | Resource | |
 | --- | --- |
 | `workflows` | A name, a description and the definition. Each save that changes the definition is checked, and kept as the workflow's next version, saved by the caller. |
 | `workflow_versions` | Every version of every definition as it was saved, with who saved it and when. Read-only. |
-| `workflow_runs` | A run, started by creating it with `workflow_id` and an `input`; it runs the version its workflow had then. Its status, output, error and timing are written by the runner. |
+| `workflow_runs` | A run, started by creating it with `workflow_id` and an `input`, or with `rerun_of` to [re-run a failed run](#re-running-a-failed-run); it runs the version its workflow had then. Its status, output, error and timing are written by the runner. |
 | `workflow_steps` | Every step of every run. Read-only. |
+| `workflow_triggers` | The trigger of each enabled workflow that has one besides `manual`: its type, status and last error. Read-only. |
 
 | `workflows` | |
 | --- | --- |
 | `schema` | The schema of its tables, for a database that has a `workflows` schema already. Default `workflows`. |
 | `secrets` | The environment variables workflows may read, by name. Startup stops when one is unset or shorter than 8 characters. |
-| `allowPrivateAddresses` | Lets the `app:http` step reach private, loopback and link-local addresses, for development and tests. Default false. |
+| `allowPrivateAddresses` | Lets the `app:http` step, and every plugin's `fetch`, reach private, loopback and link-local addresses, for development and tests. Default false. |
+| `plugins` | Packages of [workflow plugins](workflow-plugins.md) to run, by name, beside the app's own in `workflows/plugins/<name>.ts`. |
 
 Records steps act as each workflow's last editor, with the roles the project's sign-in gives them now. A project that signs people in otherwise exports its own, `async ({ id, tenant }) => [...]`, as the default of `workflows/saved-by-roles.ts` (`createAdmin` takes it as `workflows.savedByRoles`); without either, startup stops.
 
@@ -41,7 +43,7 @@ A definition is one JSON document: the workflow's trigger, and the state machine
 
 ```json
 {
-  "trigger": { "record": { "events": ["orders.created"] } },
+  "trigger": { "app:record": { "resource": "orders", "when": "status = 'placed'" } },
   "stateMachine": {
     "QueryLanguage": "JSONata",
     "StartAt": "Charge",
@@ -52,7 +54,7 @@ A definition is one JSON document: the workflow's trigger, and the state machine
         "Arguments": {
           "method": "POST",
           "url": "https://payments.example.com/charges",
-          "body": { "order_id": "{% $states.context.Execution.Input.after.id %}", "amount": "{% $states.context.Execution.Input.after.total %}" }
+          "body": { "order_id": "{% $states.context.Execution.Input.record.id %}", "amount": "{% $states.context.Execution.Input.record.total %}" }
         },
         "Retry": [{ "ErrorEquals": ["States.ALL"], "IntervalSeconds": 10, "MaxAttempts": 3, "BackoffRate": 2 }],
         "Catch": [{ "ErrorEquals": ["States.ALL"], "Next": "MarkFailed", "Assign": { "chargeError": "{% $states.errorOutput %}" } }],
@@ -61,7 +63,7 @@ A definition is one JSON document: the workflow's trigger, and the state machine
       "MarkFailed": {
         "Type": "Task",
         "Resource": "app:records.update",
-        "Arguments": { "resource": "orders", "key": "{% $states.context.Execution.Input.after.id %}", "data": { "status": "payment_failed" } },
+        "Arguments": { "resource": "orders", "key": "{% $states.context.Execution.Input.record.id %}", "data": { "status": "payment_failed" } },
         "Next": "TellOps"
       },
       "TellOps": {
@@ -69,7 +71,7 @@ A definition is one JSON document: the workflow's trigger, and the state machine
         "Resource": "app:mail.send",
         "Arguments": {
           "to": "ops@example.com",
-          "subject": "{% 'Payment failed for order ' & $states.context.Execution.Input.after.id %}",
+          "subject": "{% 'Payment failed for order ' & $states.context.Execution.Input.record.id %}",
           "text": "{% $chargeError.Cause %}"
         },
         "End": true
@@ -83,17 +85,33 @@ The document holds no layout: the [editor](#the-editor) lays the graph out from
 
 ### Triggers
 
-`trigger` holds exactly one of these; its payload is the run's input.
+`trigger` holds one key: `manual`, or a trigger type `<plugin>:<key>` with its input. The built-in ones are the `app` plugin's; a [workflow plugin](workflow-plugins.md) adds its own the same way, and `list_workflow_types` over MCP lists them all with their inputs.
 
 | Trigger | Starts a run | The input holds |
 | --- | --- | --- |
-| `"webhook": {}` | on each POST to the workflow's webhook address | `{ body, headers, query }` |
-| `"schedule": { "cron", "timezone" }` | on a 5-field cron, in an IANA time zone (default `UTC`) | `{ scheduled_at }`, ISO 8601 with the zone's offset |
-| `"mail": { "mailbox" }` | on each mail arriving in that mailbox | `{ from, to, subject, text, html, received_at, attachments }` |
-| `"record": { "events": ["<resource>.<event>"] }` | on each of those record events, such as `deals.created` | `{ event, resource, key, after, before, changed }` |
 | `"manual": {}` | when someone runs the workflow by hand | the input they give |
+| `"app:record": { "resource", "when", "key" }` | once per record that becomes ready | `{ resource, key, record }` |
 
-A save checks a trigger's shape; runs start through the API, over MCP or from the app's code. <gap>A webhook, schedule, mail or record trigger cannot start runs because the triggers are not implemented.</gap>
+A save checks a trigger's input against its type, and refuses a type the app does not have; besides triggers, runs start through the API, over MCP, from the app's code or by a [test run](#test-runs). <gap>A workflow cannot start from a webhook or a schedule because the webhook and polling triggers are not implemented.</gap>
+
+### Turning a trigger on
+
+A trigger starts runs only while its workflow is enabled: set `enabled_version` to the workflow's current `version` through the API, in the admin app or with `update_workflow`, and clear it to turn the workflow off. The trigger is registered at once on every server process, with no restart, and its status, `active` or `failing` with its last error, is the workflow's `workflow_triggers` record. A save of an enabled workflow keeps it enabled on its new version; a new version whose trigger has the same type and input keeps the running trigger as it is, and any other change stops it and starts the new one. A trigger's runs run the enabled version and act as the user who saved it, as any run acts as its version's saver.
+
+### app:record
+
+```json
+{ "app:record": { "resource": "invoices", "when": "status = 'sent' AND due_at <= now() - 3d", "key": ["due_at"] } }
+```
+
+Starts one run for each record of `resource` that becomes ready, with `{ resource, key, record }` as the run's input, so the record's fields are read as `$states.context.Execution.Input.record.<field>`. Without `when`, every record is ready once it exists, so each new record starts one run.
+
+- **`when`** is a [filter](api.md#filters) on the resource's filterable fields. `now()` may stand only in AND terms of the form `<timestamp or date field> <= now() - <duration>` (or `<`): such a term says when a record becomes ready, and the run starts at that time with no write, such as three days after an invoice's `due_at`. Any other use of `now()`, such as inside an OR, `search()` and `similar()` are refused at save, naming the term.
+- **One run per ready key:** the record's key, plus the values of the `key` fields. A record that stays ready over later writes starts no second run; one whose `due_at` changes is ready again under a new key.
+- **Who reads it:** the record is read through the API as the user who saved the enabled version, in the workflow's tenant, and `when` is checked on what they may read, so a record they cannot read, or a field they cannot see, never reaches a run. A saver who holds no role any more, or whom the API refuses, marks the trigger `failing`; the next write it reads a record on makes it active again, and it then passes over the records it missed. A key field the saver cannot read marks it `failing` too.
+- **When it looks:** a write to the resource, through the API or the database, reaches the trigger through [events](events.md), so the resource must declare some; turning a workflow on also starts runs for the records ready already, 100 per job. No periodic sweep runs.
+
+<gap>A workflow cannot start on every write of a record because an every-change trigger is not implemented; a record trigger starts once per ready key.</gap> <gap>An owner is not told when a trigger starts failing because trigger alerts are not implemented.</gap>
 
 ### Reading values by name
 
@@ -113,7 +131,7 @@ A state's `Assign` is evaluated with the variables as they were when the state w
 
 The save is refused, naming each state and field, when the document does not fit the profile:
 
-- a field does not belong to its state or has the wrong type, or the trigger is not exactly one of the above, with a 5-field cron and a known time zone;
+- a field does not belong to its state or has the wrong type, or the trigger is not exactly one of `manual` or an available `<plugin>:<key>` type with input that fits that type's schema;
 - a `Next`, `Default` or catcher names no state, a state is never reached, or a state name is used twice, Maps included;
 - a Task names a step type the app does not have, or the state type is not one of Task, Choice, Pass, Map, Wait, Succeed and Fail;
 - an expression does not parse, or reads anything but the names above: the state's input as JSONata's context (a bare field name, `$`, `$$`), `$states.input` outside an item's first state, `$states.context` but for the three reads above, a variable no state that can run before it assigns, or `$eval`;
@@ -121,7 +139,7 @@ The save is refused, naming each state and field, when the document does not fit
 
 The problem's `problems` lists them as `{ state, field, message }`, where a state inside a Map is named by its path, such as `Each/Total`. The document's JSON Schema is `definitionSchema` of `@protobase/workflows`, and `checkDefinition` runs the whole check.
 
-<gap>A save cannot refuse a Task's missing or unknown argument because checking `Arguments` per step type is not implemented.</gap> The step fails its run instead, with an error such as `Http.InvalidArguments` whose cause names the argument.
+A save refuses a Task that leaves out an argument its step type needs, as [the editor](#the-editor) describes. <gap>A save cannot refuse a Task's unknown argument because checking `Arguments` against the step type's whole schema at save is not implemented.</gap> The step fails its run instead, with an error such as `Http.InvalidArguments` whose cause names the argument.
 
 ### States
 
@@ -146,16 +164,18 @@ A failing Task or Map fails with an error name: a step type's own, such as `Http
 A workflow's record page in the admin app, `/workflows/<id>`, and its create form draw the definition as a graph to edit, and save the same document the API saves:
 
 - **The graph lays itself out.** The trigger is on top, each state is a box, a Map is a box around the states it runs for each item, and each edge is drawn from the field that names it: a state's `Next`, a Choice's rules (labelled with their condition) and its `Default` ("Otherwise"), and a Task's or Map's catchers ("On error", dashed). The graph is laid out by ELK's layered algorithm, from top to bottom, each time a state or edge is added, removed or renamed; the document keeps no positions, so the graph a person sees is the one a model or the API wrote, and the one they edit is what a model reads back. The page scrolls under the wheel; the canvas zooms with its buttons and by pinching.
-- **Adding a step.** *Add a step* adds a Task of a step type, or a Choice, Map, Wait, Pass, Succeed or Fail, named `Step 1`, `Step 2` and so on. It goes into the Map chosen, or the Map the chosen step is in, else into the workflow; it ends the run, or its item, until it is connected, and in a workflow or Map without steps it is the first.
+- **Adding a step.** *Add a step* adds a Task of any step type the app can run, its plugins' included, or a Choice, Map, Wait, Pass, Succeed or Fail, named `Step 1`, `Step 2` and so on. It goes into the Map chosen, or the Map the chosen step is in, else into the workflow; it ends the run, or its item, until it is connected, and in a workflow or Map without steps it is the first.
 - **Connecting steps.** Drag from a step's handle to another step, or tap one handle and then the other: the bottom handle sets `Next`, a Choice's *When* handle adds a rule and its *Otherwise* handle sets `Default`, a Task's or Map's *On error* handle adds a catcher of `States.ALL`, and the trigger's handle sets `StartAt`. A step leads only to steps of its own machine, so an edge into or out of a Map is refused. The chosen step's form sets the same edges with menus: *Goes on to*, each rule's and catcher's *Then goes to*, and *Otherwise goes to*.
 - **Removing.** Delete or Backspace removes the chosen step or edge, as does the form's *Remove step*. Removing a step removes the edges to it: a `Next` to it becomes `End`, and a rule, `Default` or catcher naming it goes. Removing the first step of a workflow or Map makes the first step left in it the first.
-- **A step's form.** Choosing a step opens its form under the graph: its name, which renames every edge to it, then what its type takes. A Task's form has a field for each argument of its step type, the ones it needs marked, as listed under [Step types](#step-types); a Choice's its rules and `Default`; a Map's `Items` and `MaxConcurrency`; a Wait's `Seconds`; a Pass's and a Succeed's `Output`; a Fail's `Error` and `Cause`. A field takes text, an expression (`{% ... %}`) or JSON; an emptied field is left out. *The step as JSON* edits every field of the step, such as `Retry`, `Assign` and `TimeoutSeconds`. The trigger's form picks the trigger and its schedule, mailbox or events.
+- **A step's form.** Choosing a step opens its form under the graph: its name, which renames every edge to it, then what its type takes. A Task's form has a field for each argument of its step type's input schema, the ones it needs marked, as listed under [Step types](#step-types) or by its plugin: one line of text for a string, one line for a number or `true` and `false`, a menu for an `enum`, names separated by commas for a list of strings, and JSON for anything else; a Choice's its rules and `Default`; a Map's `Items` and `MaxConcurrency`; a Wait's `Seconds`; a Pass's and a Succeed's `Output`; a Fail's `Error` and `Cause`. A field takes text, an expression (`{% ... %}`) or JSON; an emptied field is left out. *The step as JSON* edits every field of the step, such as `Retry`, `Assign` and `TimeoutSeconds`. The trigger's form picks among the app's triggers, its plugins' included, and draws a field for each input of its schema the same way, such as a record trigger's resource, `when` and `key`.
 - **Problems on their step.** The editor runs the same check as a save on every change, and shows each problem on the step it names, as a count on its box and a list and a marked field in its form; a problem with the trigger or the first step shows on the trigger, and one about the whole document above the graph. Saving writes the definition through the API, where the save hook checks it again: a definition with a problem is refused with the 400 above, whose `errors` hold each problem for the `definition` field, with its state and field in `params`.
 
-A save also refuses a Task that leaves out an argument its step type needs, such as `app:http` without `url`, unless its `Arguments` is one expression, whose value is known only when it runs. A user who may read a workflow but not change it sees the same graph and forms, locked. <gap>The editor cannot undo a single change because an undo history is not implemented.</gap>
+A save also refuses a Task that leaves out an argument its step type needs, such as `app:http` without `url`, unless its `Arguments` is one expression, whose value is known only when it runs. A user who may read a workflow but not change it sees the same graph and forms, locked. <gap>The editor cannot undo a single change because an undo history is not implemented.</gap> The editor reads the app's types from `GET /api/workflows/types`, `client.workflowTypes()` of `@protobase/client`: the same list `list_workflow_types` gives over MCP, `{ step_types, triggers }`, which only a user who may read workflows gets. A type the app cannot run, such as a polling or webhook trigger in this version, is not offered, and the check refuses it with the reason; a stored trigger of such a type, or of a type the app does not have, shows its type and input, read-only. <gap>A box on the graph cannot name a plugin's trigger or step type by its label because handing the type list to the canvas is not implemented; it shows the type's id, such as `acme:shout`.</gap>
 
 ## Step types
 
+The built-in step types are the `app` plugin's, written on the same [plugin interface](workflow-plugins.md) as any other; a plugin's step is a Task with `"Resource": "<plugin>:<key>"`. A step's `Arguments` are checked against its type's input schema before it runs: one that does not fit fails as `<Prefix>.InvalidArguments`, such as `Http.InvalidArguments`.
+
 ### app:http
 
 One request to a URL built at run time:
@@ -210,9 +230,37 @@ Each step is recorded as a `workflow_steps` record: the state, its type, the sco
 
 A workflow reads a secret only by name, `$states.context.Secrets.TICKETS_TOKEN`, and only one the config's `workflows.secrets` lists; the values are never part of the definition. Every value of the listed secrets is blanked out as `[redacted]` wherever it appears in what a run records: a step's input, output, variables, logs, error and cause, and the run's output, error and cause. In a Task's recorded input, every field whose name says it holds a secret, such as `Authorization`, `token` or `apiKey`, is blanked out too. A value an expression computes from a secret, however it changes it, such as `'Basic ' & $base64encode(...)`, is kept whole as `[redacted]`: in a Task's `Arguments` the step type gets the value and the record keeps `[redacted]`; in an `Output`, an `Assign`, a Map's `Items` or a Fail's `Error` and `Cause` the value itself is `[redacted]`, so later states read that. Read a secret in the `Arguments` of the Task that sends it. A secret that comes back changed in a step's result, such as one a server encodes in its answer, is not the value the runner looks for, and is kept as it came. A run's input is kept as its caller gave it, so a secret's value never belongs in it.
 
+### Following and debugging a run
+
+A workflow's page in the admin app lists its runs, newest first, with their status, who or what started them, when, how long they took, their version and error. A run's page, `/workflow_runs/<id>`, draws the workflow's graph as the run's version has it, the `workflow_run` [field type](plugins.md#workflow) on the run's `id`, with a mark on each state:
+
+| Mark | |
+| --- | --- |
+| Succeeded, Caught, Failed | How the state's last step ended; for a state inside a Map, the worst of its items. A failed state's box is red. |
+| Retrying | Its last try failed and a retrier tries it again. |
+| Running | The run is on it, or goes on to it next. |
+
+A state that took more than one step, by its tries, its visits or a Map's items, says how many. Choosing a state lists its steps under the graph in the order they ran, 20 at a time with *Show more*: each with its try, the Map item it ran in, its status, when it started and how long it took, its error and cause, input, output, the variables it assigned and its logs, and a link to the step's own page. Choosing the trigger shows the run's input. The page opens on the state that failed, the innermost one when a Map's item failed, so a failed run shows its error and logs at once.
+
+While a run is queued, running or waiting, the page reads the run and its steps again every second, through the API as the person, so the marks, the step lists and the run's fields change as it goes, without a reload; it stops once the run has ended. The graph marks the states of a run's first 500 steps; the run's *Steps* list has them all. <gap>The graph cannot mark the steps after a run's first 500 because reading a run's steps in more than one page for the trace is not implemented.</gap> Everything the page shows is what the run recorded, so a [secret](#secrets) shows as `[redacted]` wherever it would have been.
+
+### Re-running a failed run
+
+A failed run's page offers *Re-run from the failed step*. It opens the form for a new run with `workflow_id` and `rerun_of` filled in; creating it, through the form or `POST /api/v1/workflow_runs` with `{ "workflow_id": "...", "rerun_of": "..." }`, starts a run that:
+
+- runs on the workflow's version now, so fix the step first, and on the earlier run's input: a re-run given an `input` of its own is refused with `rerun-input`;
+- keeps the earlier run's steps, copied as they were, but the try that failed and that state's retried tries before it, so the failed state runs again from its first try and none of the steps before it runs again. A Map that runs again keeps its finished items and runs again only those that had not finished, each from where it stood;
+- is refused, and nothing starts, when the earlier run is not one of the workflow's runs the person may read (404), did not fail (`run-not-failed`), or would go on at a state the version no longer has (`rerun-refused`, naming the state).
+
+A kept step's card on the run's page says it is from the earlier run, as it finished before the re-run started; the earlier run's page lists its re-runs.
+
+### Test runs
+
+A workflow's page offers *Test run*: the form for a new run of the workflow, whose `input` takes a sample input as JSON, which every state reads as `$states.context.Execution.Input`. Creating it opens the run's page, which follows it as it runs. A test run is a run like any other: its steps do what they do, as the workflow's last editor, with the version saved last.
+
 ## Over MCP
 
-An AI client signed in to the app's [MCP endpoint](mcp.md#workflows) finds, makes, changes and test-runs workflows as the person: it lists the step types and triggers with their arguments, reads and validates definitions, saves one whole or by a small edit, starts a run with an input, and reads each of the run's steps with its input, output, logs and error. The endpoint's instructions describe this language, and a refused definition comes back with its problems, each naming the state and field.
+An AI client signed in to the app's [MCP endpoint](mcp.md#workflows) finds, makes, changes and test-runs workflows as the person: it lists the step types and triggers with their arguments, reads and validates definitions, saves one whole or by a small edit, starts a run with an input, reads each of the run's steps with its input, output, logs and error, and re-runs a failed run from its failed step once the workflow is fixed. The endpoint's instructions describe this language, and a refused definition comes back with its problems, each naming the state and field.
 
 ## Who may do what
 
@@ -220,9 +268,9 @@ The workflow resources take only [named grants](access.md#resources-that-need-na
 
 | Grant | |
 | --- | --- |
-| `workflows.create`, `workflows.update`, `workflows.delete` | Make, change and delete workflows. Each save that changes the definition makes the saver the workflow's last editor, whom its records steps act as. |
+| `workflows.create`, `workflows.update`, `workflows.delete` | Make, change and delete workflows, and turn them on and off. Each save that changes the definition makes the saver the workflow's last editor, whom its records steps and its trigger act as. |
 | `workflow_runs.create` | Run a workflow, with any input. The API writes only the fields a caller reads, so it goes with `workflow_runs.read`, and the caller must read the workflow too. |
-| `workflows.read`, `workflow_versions.read`, `workflow_runs.read`, `workflow_steps.read` | Read workflows, their versions, runs and steps, the steps' inputs and outputs included. |
+| `workflows.read`, `workflow_versions.read`, `workflow_runs.read`, `workflow_steps.read`, `workflow_triggers.read` | Read workflows, their versions, runs, steps and triggers, the steps' inputs and outputs included. |
 
 ```ts
 defineRoles({
@@ -231,7 +279,7 @@ defineRoles({
 })
 ```
 
-All four are scoped to the tenant like any resource with `.tenant()`. A run takes its workflow's tenant; a start of another tenant's workflow is refused as one of a workflow that is not there.
+All five are scoped to the tenant like any resource with `.tenant()`. A run takes its workflow's tenant; a start of another tenant's workflow is refused as one of a workflow that is not there.
 
 ## How a run is run
 
@@ -239,7 +287,7 @@ The runner is `@protobase/workflows`, a package with no other Protobase dependen
 
 - A run is run in **segments**, each a `workflows.segment` job whose payload is the run's id alone: one runs the run from where it stands to its next wait, then queues the next. A Wait whose time is still ahead, or a retry's delay, saves its step with the time the run goes on, ends the segment and queues the next one for that time, so a waiting run holds no worker. A segment hands the rest of the run on after a minute of steps.
 - Where a run stands is read from its saved steps. A Task's step, and one with a time the run goes on at, is saved before the next state runs; the steps of other states are kept and saved with it, or as the segment ends. Each save is **one statement**, unique by each step's scope and number, so a second segment of the same run that finds one taken stops.
-- A worker that stops or dies mid-step leaves that step unsaved: its job is tried again and takes the run up from its last saved step, so a saved step never runs again, and the step that was in progress runs **at least once**, as do the steps kept since the last save, which give the same records again. A step whose effect happened before its result was saved, such as a request that was sent, happens again. Every try of a step gets the same idempotency key, for a step type whose receiver dedupes by it, and `app:mail.send` makes it the mail's Message-ID. A job whose worker died is tried again once its timeout, 10 minutes, has passed.
+- A worker that stops or dies mid-step leaves that step unsaved: its job is tried again and takes the run up from its last saved step, so a saved step never runs again, and the step that was in progress runs **at least once**, as do the steps kept since the last save, which give the same records again. A step whose effect happened before its result was saved, such as a request that was sent, happens again. Every try of a step gets the same idempotency key, for a step type whose receiver dedupes by it, and `app:mail.send` makes it the mail's Message-ID. `app:records.create` keeps it with the records it creates, in their transaction, so a try after they committed creates none again and returns them as the first try created them. A job whose worker died is tried again once its timeout, 10 minutes, has passed.
 - A Map's items run in the segment that reaches them, each item's steps saved under its own scope; an item that waits ends the segment once the others running settle, and the next segment takes each item up where it stands. A Map's `Items` is evaluated again by a segment that takes up an unfinished Map.
 - JSONata runs in the server's process under a time and a depth limit per expression; it reaches no file, network or code of the app.