@protobase/server 0.67.8 → 0.67.10

package/dist/workflows/mcp/type-catalog.js

@@ -0,0 +1,144 @@
+//#region src/workflows/mcp/type-catalog.ts
+const needs = (takes) => ({
+	required: true,
+	takes
+});
+const may = (takes) => ({
+	required: false,
+	takes
+});
+const resource = needs("the resource's name, as list_resources gives it");
+const key = needs("the record's key");
+const refused = ["Records.Refused: the API refused it, its status and message in the cause", "Records.InvalidArguments: an argument has the wrong type, named in the cause"];
+/** The step types a Task names as its `Resource`, as the workflows reference describes them. */
+const stepTypeCatalog = [
+	{
+		resource: "app:http",
+		does: "Sends one HTTP request to a public address and reads the answer.",
+		arguments: {
+			url: needs("an http or https URL"),
+			method: may("GET (default), POST, PUT, PATCH or DELETE"),
+			headers: may("an object of text values"),
+			query: may("an object of text values, added to the URL's query"),
+			body: may("text sent as it is, a file value sent as its bytes, any other value sent as JSON; a GET sends none"),
+			response: may("how the answer's body is read: json (default; empty is null), text, or file (kept as a file value of the run)")
+		},
+		result: "{ status, headers, body }",
+		errors: [
+			"Http.Status: a status outside 2xx; the cause names it with the start of the body",
+			"Http.Network: no answer",
+			"Http.InvalidArguments: an argument has the wrong type, named in the cause",
+			"Http.InvalidBody: response json, and the body is not JSON",
+			"Http.AddressRefused: the host is not a public address",
+			"Http.ResponseTooLarge: a body over 10 MiB"
+		]
+	},
+	{
+		resource: "app:records.create",
+		does: "Creates records of the app's resources, as the workflow's last editor.",
+		arguments: {
+			resource,
+			data: needs("an object of field values, or a list of them, created in one batch: all or none")
+		},
+		result: "the created record, or the list of them",
+		errors: refused
+	},
+	{
+		resource: "app:records.update",
+		does: "Updates one record, as the workflow's last editor.",
+		arguments: {
+			resource,
+			key,
+			data: needs("an object of the field values to change")
+		},
+		result: "the updated record",
+		errors: refused
+	},
+	{
+		resource: "app:records.get",
+		does: "Reads one record, as the workflow's last editor.",
+		arguments: {
+			resource,
+			key
+		},
+		result: "the record",
+		errors: refused
+	},
+	{
+		resource: "app:records.list",
+		does: "Lists records, as the workflow's last editor.",
+		arguments: {
+			resource,
+			filter: may("a filter in the API's syntax, such as status = \"open\""),
+			order_by: may("such as \"created_at desc\""),
+			limit: may("how many at most")
+		},
+		result: "{ records }",
+		errors: refused
+	},
+	{
+		resource: "app:mail.send",
+		does: "Sends a mail from the app's own sender.",
+		arguments: {
+			to: needs("one address, or a list of at most 50"),
+			subject: needs("one line of text"),
+			text: needs("the body as text"),
+			html: may("the body as HTML too"),
+			attachments: may("a list of file values the run keeps, at most 10 MiB together")
+		},
+		result: "{ message_id }",
+		errors: ["Mail.InvalidArguments: an argument has the wrong type, named in the cause", "States.TaskFailed: the app sends no mail, or the mailer refused it"]
+	},
+	{
+		resource: "app:piece",
+		does: "Runs an action of a connector. Not implemented yet: a run fails it.",
+		arguments: {
+			piece: needs("the connector's name"),
+			action: needs("one of its actions"),
+			connection: needs("the connection holding its sign-in"),
+			props: may("the action's arguments, by name")
+		},
+		result: "what the action returns",
+		errors: ["Piece.Error: always, until connectors are implemented"]
+	}
+];
+/** The triggers a definition's `trigger` holds exactly one of. */
+const triggerCatalog = [
+	{
+		trigger: "manual",
+		example: { manual: {} },
+		starts: "when someone runs the workflow, such as with run_workflow",
+		input: "the input they give"
+	},
+	{
+		trigger: "webhook",
+		example: { webhook: {} },
+		starts: "on each POST to the workflow's webhook address",
+		input: "{ body, headers, query }"
+	},
+	{
+		trigger: "schedule",
+		example: { schedule: {
+			cron: "0 6 * * 1-5",
+			timezone: "Europe/Amsterdam"
+		} },
+		starts: "on a 5-field cron, in an IANA time zone (default UTC)",
+		input: "{ scheduled_at }, ISO 8601 with the zone's offset"
+	},
+	{
+		trigger: "mail",
+		example: { mail: { mailbox: "support" } },
+		starts: "on each mail arriving in that mailbox",
+		input: "{ from, to, subject, text, html, received_at, attachments }"
+	},
+	{
+		trigger: "record",
+		example: { record: { events: ["orders.created"] } },
+		starts: "on each of those record events, <resource>.<event>",
+		input: "{ event, resource, key, after, before, changed }"
+	}
+];
+/** Only manual runs start for now: a save takes the other triggers, which start nothing yet. */
+const triggerNote = "Runs start only by hand (run_workflow) for now: a workflow saves with any trigger, and the other triggers start no runs yet.";
+//#endregion
+export { stepTypeCatalog, triggerCatalog, triggerNote };

package/dist/workflows/mcp/workflow-instructions.d.ts

@@ -0,0 +1,7 @@
+//#region src/workflows/mcp/workflow-instructions.d.ts
+/**
+ * What the MCP endpoint tells a client about workflows, beside reading records: the language, in the named-reads
+ * profile of the States Language with JSONata, and how the workflow tools find, make, change and test-run them.
+ */
+export declare const workflowInstructions: string;
+//#endregion

package/dist/workflows/mcp/workflow-instructions.js

@@ -0,0 +1,77 @@
+import { limits } from "@protobase/workflows";
+/**
+* What the MCP endpoint tells a client about workflows, beside reading records: the language, in the named-reads
+* profile of the States Language with JSONata, and how the workflow tools find, make, change and test-run them.
+*/
+const workflowInstructions = [
+	"Workflows: list_workflow_types names the step types and triggers with their arguments and inputs; list_workflows and get_workflow read workflows; validate_workflow checks a definition without saving it; create_workflow and update_workflow save one; run_workflow starts a run with an input, and get_workflow_run reads it with each step's input, output, logs and error. A run goes on in the background: read it again until its status is succeeded or failed, then fix the step that failed with update_workflow and run it again.",
+	"A definition is one JSON document: { \"trigger\": <exactly one trigger>, \"stateMachine\": { \"QueryLanguage\": \"JSONata\", \"StartAt\": \"<state>\", \"States\": { \"<state>\": <state>, ... } } }, the States Language with JSONata expressions, in a profile where every value is read by name. It holds no layout.",
+	"States: Task { Resource: <step type>, Arguments, TimeoutSeconds, Retry, Catch }; Pass { Output, Assign }; Choice { Choices: [{ Condition, Next, Output?, Assign? }], Default }; Map { Items, ItemProcessor: { StartAt, States }, MaxConcurrency }; Wait { Seconds | Timestamp }; Succeed { Output }; Fail { Error, Cause }. Every state may have Comment, Output and Assign. Task, Pass, Map and Wait have exactly one of Next (a state name) and End: true. State names are unique across the document, Maps included, and every state must be reachable from StartAt. InputPath, Parameters, ResultPath and the other JSONPath fields, and Parallel, are not part of the profile.",
+	"Expressions: a string that is whole \"{% ... %}\" is a JSONata expression whose value, of any type, the field takes; any other string is literal text. Build text inside one expression with &: \"{% 'Order ' & $order.id %}\". Expressions sit at any depth in Arguments, Output and Assign, and in Items, Condition, Seconds, Timestamp, Error and Cause.",
+	"Reading values by name, the only reads allowed: $states.context.Execution.Input (the run's input, in every state), $states.context.Execution.StartTime, $states.context.Secrets.<NAME> (a secret the app lists), $<variable> (assigned by a state that runs before), $states.result (a Task's or Map's result, in its Output and Assign), $states.errorOutput ({ Error, Cause }, in a Catch rule's Output and Assign), $states.input (the item, only in the first state of a Map's ItemProcessor). Never a bare field name, $ or $$ on its own, or $eval. Keep a result for later states with \"Assign\": { \"order\": \"{% $states.result %}\" }, read as $order from the next state on; a state inside a Map may not assign a name an outer state assigns.",
+	`Errors: a failing Task or Map fails with an error name, its step type's own (list_workflow_types names them), States.Timeout, States.TaskFailed, or States.QueryEvaluationError for an expression that failed. Retry: [{ ErrorEquals: ["States.ALL"], IntervalSeconds, MaxAttempts (retries after the first try, at most ${limits.retryAttempts}), BackoffRate }]; Catch: [{ ErrorEquals, Next, Assign }] goes on to Next once no retry is left; without a Catch the run fails. A Choice whose rules all fail and that has no Default fails with States.NoChoiceMatched.`,
+	`Limits: ${limits.states} states, a Map's MaxConcurrency ${limits.mapConcurrency}, a Task's TimeoutSeconds ${limits.taskTimeoutSeconds}.`,
+	`A saved or validated definition that does not fit is refused with problems, each { state, field, message }: the state (a Map's inner state as Map/State), the field such as Arguments.url, and what was expected. Fix those fields and try again; nothing was saved. An example: ${JSON.stringify({
+		trigger: { manual: {} },
+		stateMachine: {
+			QueryLanguage: "JSONata",
+			StartAt: "GetQuote",
+			States: {
+				GetQuote: {
+					Type: "Task",
+					Resource: "app:records.get",
+					Arguments: {
+						resource: "quotes",
+						key: "{% $states.context.Execution.Input.quote_id %}"
+					},
+					Assign: { quote: "{% $states.result %}" },
+					Next: "IsDraft"
+				},
+				IsDraft: {
+					Type: "Choice",
+					Choices: [{
+						Condition: "{% $quote.status = 'draft' %}",
+						Next: "Notify"
+					}],
+					Default: "NotADraft"
+				},
+				NotADraft: {
+					Type: "Fail",
+					Error: "Quote.NotDraft",
+					Cause: "{% 'Quote ' & $quote.id & ' is not a draft' %}"
+				},
+				Notify: {
+					Type: "Task",
+					Resource: "app:http",
+					Arguments: {
+						method: "POST",
+						url: "https://hooks.example.com/quotes",
+						body: {
+							id: "{% $quote.id %}",
+							total: "{% $quote.total %}"
+						}
+					},
+					Retry: [{
+						ErrorEquals: ["States.ALL"],
+						IntervalSeconds: 10,
+						MaxAttempts: 3
+					}],
+					Catch: [{
+						ErrorEquals: ["States.ALL"],
+						Next: "Failed",
+						Assign: { notifyError: "{% $states.errorOutput %}" }
+					}],
+					Output: "{% $states.result.body %}",
+					End: true
+				},
+				Failed: {
+					Type: "Fail",
+					Error: "Notify.Failed",
+					Cause: "{% $notifyError.Cause %}"
+				}
+			}
+		}
+	})}`
+].join("\n");
+//#endregion
+export { workflowInstructions };

package/dist/workflows/mcp/workflow-read-tools.d.ts

@@ -0,0 +1,6 @@
+import { AssistantTool, ToolContext } from "../../assistant/tools.js";
+import "../../index.js";
+//#region src/workflows/mcp/workflow-read-tools.d.ts
+/** The tools that read workflows, their types and runs, and check definitions. */
+export declare const workflowReadTools: () => AssistantTool<ToolContext>[];
+//#endregion

package/dist/workflows/mcp/workflow-read-tools.js

@@ -0,0 +1,209 @@
+import { defineTool } from "../../assistant/tools.js";
+import { refused } from "../../assistant/record-tool-args.js";
+import { stepTypeNames } from "../step-types.js";
+import { mergePatch } from "./merge-patch.js";
+import { stepTypeCatalog, triggerCatalog, triggerNote } from "./type-catalog.js";
+import { definitionParameter, editParameter, idOf, idParameter, objectOf, pageSizeOf, textOf } from "./workflow-tool-args.js";
+import { checkDefinition } from "@protobase/workflows";
+//#region src/workflows/mcp/workflow-read-tools.ts
+const reads = {
+	readOnlyHint: true,
+	openWorldHint: false
+};
+const listed = [
+	"id",
+	"name",
+	"description",
+	"version",
+	"updated_at"
+];
+/** The step types and triggers a definition may name, with their arguments, results, errors and run inputs. */
+const listWorkflowTypesTool = defineTool({
+	name: "list_workflow_types",
+	description: "Lists what a workflow definition may name, as JSON ({ step_types, triggers }): each step type a Task names as its Resource, with its Arguments (required or not, and what each takes), its result and the errors it fails with; and each trigger, how the definition holds it and the input a run gets from it.",
+	parameters: {
+		type: "object",
+		properties: {}
+	},
+	annotations: reads,
+	run: async () => JSON.stringify({
+		step_types: stepTypeCatalog,
+		triggers: triggerCatalog,
+		note: triggerNote
+	})
+});
+/** The workflows the caller may read, a page at a time, without their definitions. */
+const listWorkflowsTool = defineTool({
+	name: "list_workflows",
+	description: "Lists the workflows you may read, newest change first, as JSON ({ items, next_page_token }), each with its id, name, description and version but not its definition: get_workflow reads that. filter uses AIP-160 on name, such as name = \"Daily report\"; pass next_page_token back as page_token for the next page.",
+	parameters: {
+		type: "object",
+		properties: {
+			filter: {
+				type: "string",
+				description: "Such as name = \"Daily report\"."
+			},
+			page_size: {
+				type: "integer",
+				minimum: 1,
+				maximum: 100,
+				description: "Workflows per page, 20 by default."
+			},
+			page_token: {
+				type: "string",
+				description: "The next_page_token of the page before."
+			}
+		}
+	},
+	annotations: reads,
+	run: async (args, context) => {
+		const params = {
+			fields: listed,
+			order_by: "updated_at desc",
+			page_size: pageSizeOf(args.page_size, 20, 100),
+			...textOf(args.filter) && { filter: textOf(args.filter) },
+			...textOf(args.page_token) && { page_token: textOf(args.page_token) }
+		};
+		return context.records.list("workflows", params).then((page) => JSON.stringify({
+			items: page.items.map(({ etag: _etag, permissions: _permissions, ...item }) => item),
+			next_page_token: page.next_page_token
+		}), refused);
+	}
+});
+/** One workflow with its definition and the etag an update can pass. */
+const getWorkflowTool = defineTool({
+	name: "get_workflow",
+	description: "Reads one workflow by its id, as JSON ({ workflow, etag }): its name, description, version and whole definition. Pass the etag to update_workflow to fail when someone changed it since.",
+	parameters: {
+		type: "object",
+		properties: { id: idParameter },
+		required: ["id"]
+	},
+	annotations: reads,
+	run: async (args, context) => {
+		const id = idOf(args);
+		if (!id) return "Pass the workflow's id as { \"id\": \"<id>\" }.";
+		return context.records.get("workflows", id).then(({ record, etag }) => JSON.stringify({
+			workflow: record,
+			etag
+		}), refused);
+	}
+});
+const checked = (definition) => {
+	const problems = checkDefinition(definition, { resources: stepTypeNames });
+	return JSON.stringify(problems.length > 0 ? {
+		valid: false,
+		problems
+	} : { valid: true });
+};
+/** Checks a definition, or a saved one with an edit, without saving anything. */
+const validateWorkflowTool = defineTool({
+	name: "validate_workflow",
+	description: "Checks a definition as a save checks it, and saves nothing: pass a whole definition, or a workflow's id with an edit to check that edit of its saved definition. Returns JSON { valid: true }, or { valid: false, problems }, each problem { state, field, message } naming the state, the field and what was expected.",
+	parameters: {
+		type: "object",
+		properties: {
+			definition: definitionParameter,
+			id: idParameter,
+			edit: editParameter
+		}
+	},
+	annotations: reads,
+	run: async (args, context) => {
+		const id = idOf(args);
+		const edit = objectOf(args.edit);
+		if (args.definition !== void 0 && id === void 0 && edit === void 0) return checked(args.definition);
+		if (args.definition === void 0 && id && edit) return context.records.get("workflows", id).then(({ record }) => checked(mergePatch(record.definition, edit)), refused);
+		return "Pass either { \"definition\": { ... } } or { \"id\": \"<id>\", \"edit\": { ... } }.";
+	}
+});
+const runFields = [
+	"id",
+	"workflow_id",
+	"version",
+	"status",
+	"input",
+	"output",
+	"error",
+	"cause",
+	"resume_at",
+	"created_at",
+	"finished_at",
+	"duration_ms"
+];
+const stepFields = [
+	"state",
+	"scope",
+	"seq",
+	"type",
+	"attempt",
+	"status",
+	"input",
+	"output",
+	"assigned",
+	"logs",
+	"error",
+	"cause",
+	"next",
+	"resume_at",
+	"duration_ms"
+];
+/** A run with its steps in the order they ran, a page at a time. */
+const getWorkflowRunTool = defineTool({
+	name: "get_workflow_run",
+	description: "Reads a run by its id, as JSON ({ run, steps, next_page_token }): its status (queued, running, waiting, succeeded or failed), input, output, error and cause, and its steps in the order they ran, each with its state, scope (empty, or the Map item it ran in), try, status (succeeded, retrying, caught or failed), input, output, assigned variables, logs, error and cause. A run goes on in the background: read it again while it is queued, running or waiting. Pass state to read only that state's steps; pass next_page_token back as page_token for more steps.",
+	parameters: {
+		type: "object",
+		properties: {
+			run_id: {
+				type: "string",
+				description: "The run's id, as run_workflow gives it."
+			},
+			state: {
+				type: "string",
+				description: "Only this state's steps."
+			},
+			page_size: {
+				type: "integer",
+				minimum: 1,
+				maximum: 100,
+				description: "Steps per page, 20 by default."
+			},
+			page_token: {
+				type: "string",
+				description: "The next_page_token of the page before."
+			}
+		},
+		required: ["run_id"]
+	},
+	annotations: reads,
+	run: async (args, context) => {
+		const id = textOf(args.run_id);
+		if (!id) return "Pass the run's id as { \"run_id\": \"<id>\" }.";
+		const run = await context.records.get("workflow_runs", id, { fields: runFields }).then(({ record }) => record, refused);
+		if (typeof run === "string") return run;
+		const state = textOf(args.state);
+		const params = {
+			filter: `run_id = ${JSON.stringify(id)}${state ? ` AND state = ${JSON.stringify(state)}` : ""}`,
+			fields: stepFields,
+			order_by: "id",
+			page_size: pageSizeOf(args.page_size, 20, 100),
+			...textOf(args.page_token) && { page_token: textOf(args.page_token) }
+		};
+		return context.records.list("workflow_steps", params).then((page) => JSON.stringify({
+			run,
+			steps: page.items.map(({ etag: _etag, permissions: _permissions, ...step }) => step),
+			next_page_token: page.next_page_token
+		}), refused);
+	}
+});
+/** The tools that read workflows, their types and runs, and check definitions. */
+const workflowReadTools = () => [
+	listWorkflowTypesTool,
+	listWorkflowsTool,
+	getWorkflowTool,
+	validateWorkflowTool,
+	getWorkflowRunTool
+];
+//#endregion
+export { getWorkflowRunTool, getWorkflowTool, listWorkflowTypesTool, listWorkflowsTool, validateWorkflowTool, workflowReadTools };

package/dist/workflows/mcp/workflow-tool-args.js

@@ -0,0 +1,35 @@
+import { problemOf } from "../../error-handler.js";
+import { refused } from "../../assistant/record-tool-args.js";
+//#region src/workflows/mcp/workflow-tool-args.ts
+const idParameter = {
+	type: "string",
+	description: "The workflow's id, as list_workflows gives it."
+};
+const definitionParameter = {
+	type: "object",
+	description: "The whole definition: { \"trigger\": { ... }, \"stateMachine\": { \"QueryLanguage\": \"JSONata\", \"StartAt\": ..., \"States\": { ... } } }, as the server's instructions describe it."
+};
+const editParameter = {
+	type: "object",
+	description: "A small edit of the saved definition as a JSON Merge Patch (RFC 7396): 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. Such as { \"stateMachine\": { \"States\": { \"Fetch\": { \"Arguments\": { \"url\": \"https://...\" } }, \"Old\": null } } }."
+};
+const idOf = (args) => typeof args.id === "string" && args.id ? args.id : void 0;
+const objectOf = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+const textOf = (value) => typeof value === "string" ? value : void 0;
+/** A page size given as a whole number, cut to `max`; `fallback` when none is given. */
+const pageSizeOf = (value, fallback, max) => typeof value === "number" && Number.isInteger(value) && value > 0 ? Math.min(value, max) : fallback;
+/**
+* A save the workflow check refused, as `{ error, message, problems }`, each problem naming the state and field and
+* what was expected; any other refusal as `refused` words it.
+*/
+const workflowRefused = (error) => {
+	const problem = problemOf(error);
+	if (problem?.slug === "invalid-workflow") return JSON.stringify({
+		error: problem.slug,
+		message: "The definition does not fit the language; nothing was saved. Fix each problem and try again.",
+		problems: problem.extras.problems
+	});
+	return refused(error);
+};
+//#endregion
+export { definitionParameter, editParameter, idOf, idParameter, objectOf, pageSizeOf, textOf, workflowRefused };

package/dist/workflows/mcp/workflow-write-tools.d.ts

@@ -0,0 +1,7 @@
+import { AssistantTool, ToolContext } from "../../assistant/tools.js";
+import { WriteRecordToolsInput } from "../../assistant/write-tool-limits.js";
+import "../../index.js";
+//#region src/workflows/mcp/workflow-write-tools.d.ts
+/** The tools that save and run workflows, on the resources `input` allows. */
+export declare const workflowWriteTools: (input?: WriteRecordToolsInput) => AssistantTool<ToolContext>[];
+//#endregion

package/dist/workflows/mcp/workflow-write-tools.js

@@ -0,0 +1,149 @@
+import { notFound } from "../../problem.js";
+import { defineTool } from "../../assistant/tools.js";
+import { refused } from "../../assistant/record-tool-args.js";
+import { createApproval, updateApproval } from "../../assistant/write-prompts.js";
+import { approvalTexts, recordBefore } from "../../assistant/record-before.js";
+import { notApproved, onlyNote, outside } from "../../assistant/write-tool-limits.js";
+import { mergePatch } from "./merge-patch.js";
+import { definitionParameter, editParameter, idOf, idParameter, objectOf, textOf, workflowRefused } from "./workflow-tool-args.js";
+//#region src/workflows/mcp/workflow-write-tools.ts
+/**
+* `create_workflow`, `update_workflow` and `run_workflow`: saving and running workflows as the caller, through the
+* resources' access rules and the save check, each after the user approves it in their client, as the record write
+* tools ask. A refused definition comes back with its problems, each naming the state and field.
+*/
+const writes = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	openWorldHint: false
+};
+const nameParameter = {
+	type: "string",
+	description: "A name, 1 to 100 characters."
+};
+const descriptionParameter = {
+	type: "string",
+	description: "What it does, for people; at most 2000 characters."
+};
+const saved = (record, etag) => JSON.stringify({
+	id: record.id,
+	version: record.version,
+	etag
+});
+/** Creates a workflow once the user approves it; a definition the check refuses saves nothing. */
+const createWorkflowTool = (input = {}) => defineTool({
+	name: "create_workflow",
+	description: `Creates a workflow from its name and whole definition, checked as validate_workflow checks it, and returns JSON { id, version, etag }. A definition that does not fit is refused with { error, problems }, each problem naming the state, the field and what was expected; nothing is saved then. The user approves each save in their client first.${onlyNote(input)}`,
+	parameters: {
+		type: "object",
+		properties: {
+			name: nameParameter,
+			description: descriptionParameter,
+			definition: definitionParameter
+		},
+		required: ["name", "definition"]
+	},
+	annotations: writes,
+	run: async (args, context) => {
+		const name = textOf(args.name);
+		const definition = objectOf(args.definition);
+		if (!name || !definition) return "Pass { \"name\": \"<name>\", \"definition\": { \"trigger\": ..., \"stateMachine\": ... } }.";
+		const refusal = outside(input, "workflows");
+		if (refusal) return refusal;
+		const data = {
+			name,
+			definition,
+			...textOf(args.description) !== void 0 && { description: textOf(args.description) }
+		};
+		const { text, described } = await approvalTexts(context, "workflows");
+		const answer = await context.approve(createApproval(text, described, data));
+		if (answer !== "approved") return notApproved(answer);
+		return context.records.create("workflows", data).then(({ record, etag }) => saved(record, etag), workflowRefused);
+	}
+});
+/** Changes a workflow's definition by an edit or a whole new one, or its name or description, once the user approves it. */
+const updateWorkflowTool = (input = {}) => defineTool({
+	name: "update_workflow",
+	description: `Changes a workflow: its definition by a small edit (edit, a JSON Merge Patch of the saved definition) or whole (definition), and its name or description. The changed definition is checked as validate_workflow checks it and saved as the workflow's next version; runs started before keep theirs. Returns JSON { id, version, etag }. A definition that does not fit is refused with { error, problems }, each naming the state, the field and what was expected; nothing is saved then. Pass the etag get_workflow gave to fail when someone changed it since. The user approves each save in their client first.${onlyNote(input)}`,
+	parameters: {
+		type: "object",
+		properties: {
+			id: idParameter,
+			edit: editParameter,
+			definition: definitionParameter,
+			name: nameParameter,
+			description: descriptionParameter,
+			etag: {
+				type: "string",
+				description: "The etag get_workflow gave, to fail when the workflow changed since."
+			}
+		},
+		required: ["id"]
+	},
+	annotations: writes,
+	run: async (args, context) => {
+		const id = idOf(args);
+		const edit = objectOf(args.edit);
+		const whole = objectOf(args.definition);
+		if (!id || edit && whole) return "Pass { \"id\": \"<id>\" } with either an edit or a whole definition, and any name or description to change.";
+		const refusal = outside(input, "workflows");
+		if (refusal) return refusal;
+		const before = await recordBefore(context, "workflows", id, textOf(args.etag) || void 0);
+		if (typeof before === "string") return before;
+		if (edit && !before) return refused(notFound("No workflows with this key that you may read"));
+		const definition = edit ? mergePatch(before.record.definition, edit) : whole;
+		const data = {
+			...definition !== void 0 && { definition },
+			...textOf(args.name) !== void 0 && { name: textOf(args.name) },
+			...textOf(args.description) !== void 0 && { description: textOf(args.description) }
+		};
+		if (Object.keys(data).length === 0) return "Pass an edit, a definition, a name or a description to change; nothing was saved.";
+		const { text, described } = await approvalTexts(context, "workflows");
+		const answer = await context.approve(updateApproval(text, described, id, before?.record ?? {}, data));
+		if (answer !== "approved") return notApproved(answer);
+		const etag = textOf(args.etag) || (edit ? before.etag : void 0);
+		return context.records.update("workflows", id, data, { ...etag && { etag } }).then(({ record, etag: next }) => saved(record, next), workflowRefused);
+	}
+});
+/** Starts a run of a workflow with an input once the user approves it. */
+const runWorkflowTool = (input = {}) => defineTool({
+	name: "run_workflow",
+	description: `Starts a run of a workflow's current version with an input, which its states read as $states.context.Execution.Input, and returns JSON { run_id, status }. The run goes on in the background, doing what its steps do (requests, mail, record writes) as the workflow's last editor: read it with get_workflow_run until its status is succeeded or failed. The user approves each run in their client first.${onlyNote(input)}`,
+	parameters: {
+		type: "object",
+		properties: {
+			id: idParameter,
+			input: { description: "The run's input, any JSON value, at most 1 MiB; an empty object by default." }
+		},
+		required: ["id"]
+	},
+	annotations: {
+		...writes,
+		openWorldHint: true
+	},
+	run: async (args, context) => {
+		const id = idOf(args);
+		if (!id) return "Pass { \"id\": \"<id>\", \"input\": { ... } }.";
+		const refusal = outside(input, "workflow_runs");
+		if (refusal) return refusal;
+		const data = {
+			workflow_id: id,
+			input: args.input ?? {}
+		};
+		const { text, described } = await approvalTexts(context, "workflow_runs");
+		const answer = await context.approve(createApproval(text, described, data));
+		if (answer !== "approved") return notApproved(answer);
+		return context.records.create("workflow_runs", data).then(({ record }) => JSON.stringify({
+			run_id: record.id,
+			status: record.status
+		}), refused);
+	}
+});
+/** The tools that save and run workflows, on the resources `input` allows. */
+const workflowWriteTools = (input = {}) => [
+	createWorkflowTool(input),
+	updateWorkflowTool(input),
+	runWorkflowTool(input)
+];
+//#endregion
+export { createWorkflowTool, runWorkflowTool, updateWorkflowTool, workflowWriteTools };

package/dist/workflows/options.d.ts

@@ -0,0 +1,27 @@
+import { TenantValue } from "../types.js";
+//#region src/workflows/options.d.ts
+/** Workflows made in the admin app (`workflows: {}`), kept with their runs in a schema of the app's database. */
+export type WorkflowsOptions = {
+  /** The schema of the workflows, their versions, runs and steps; default `workflows`. */
+  schema?: string;
+  /**
+   * The environment variables workflows may read, each as `$states.context.Secrets.<NAME>`; no other is reachable.
+   * Their values are blanked out of all a run records. Startup stops when one is unset or shorter than 8 characters.
+   */
+  secrets?: string[];
+  /**
+   * The roles a workflow's last editor holds now in its tenant, which its records steps act with. Default: read from
+   * the project's Better Auth (`auth`); a project that signs people in otherwise passes its own, which the CLI reads
+   * from the default export of `workflows/saved-by-roles.ts`.
+   */
+  savedByRoles?: (user: {
+    id: string;
+    tenant?: TenantValue;
+  }) => Promise<string[]>;
+  /**
+   * Lets the `app:http` step reach private, loopback and link-local addresses, for development and tests. Default
+   * false: a URL whose host resolves to one fails the step, so a workflow cannot reach the app's own network.
+   */
+  allowPrivateAddresses?: boolean;
+};
+//#endregion